JReviews Manual

Last update: January 9th, 2014

Copyright © 2010-2014 ClickFWD LLC

Chapter 1 JReviews Overview

1.1 How does JReviews work

JReviews integrates with the core Joomla content system and extends its functionality.

Joomla articles have a single field, which can be split into Summary and Description, but with JReviews you will be able to add any number of other content fields, such as: text fields, text areas, single selects, multiple selects, website fields, email fields, date fields, checkboxes, etc.

With JReviews, articles become listings that can be reviewed and rated by designated JReviews editors and users.

Editor and user reviews can also have any number of custom fields, and you can define custom ratings with unlimited criteria.

Different types of listings can be created, for example: Products, Books, Movies, Games, Restaurants, Hotels, Classifieds, Events, News, etc.

1.1.1 Example of a listing:

This is the top part of the listing detail page that contains information about the listing (summary/decription text, custom fields with location, contant and other hotel information, rating stars, action buttons, main listing photo, etc.):

Below the listing info there are photo and video galleries. Photos and videos can be submitted either by listing owner or by site visitors as well if you allowed them that. Photos and videos are not the only type of media JReviews provides, there are also attachments and audio files. For every media type there are multiple display layouts available, this is one option:

With GeoMaps add-on for JReviews it is possible to include the map for the listing with streetview and directions search:

The powerful listing detail page widgets can be included to show related listings:

At the bottom of the listing detail page you will find the reviews sections where editors and users can review the listing:

A live example of this listing can be found on the JReviews demo site.

1.2 Planning and organizing your JReviews setup

1.2.1 Listing Types

Listing types are different types of content that you can setup. Basically, with listing types you define how the listing and review forms will look like (which fields they will include).

Examples of listing types you might create:

Businesses - a type of listing that will include field groups (fields) like Location (City, Address, Postcode), Contact Info (Phone number, Email address, Website url), etc.

Hotels - this listing type would include Location and Contact Info field groups the same as the business listing type, but it can also include additional Hotel Info field group with fields like Hotel Amenities, Pricing, etc.

Restaurants - similarly to hotels and businesses, this listing type would include Location and Contact Info field groups as well, but you can also create additional field group(s) for entering information about restaurant's Cuisine and Menus.

Products - this type of listing would have a Product Info field group with fields like Brand, Model, Release Date, Product Website, etc.

Movies - a type of listing that would include a field group with information about the movie (Year, Directors, Actors, Genre) and a field group with affiliate links where visitors can buy/rent movies (Amazon, iTunes, Netflix)

Events - it would contain event information fields like Event Date and Event Venue.

Listing Types will be assigned to Joomla Categories.

1.2.2 Directories & Categories

Since JReviews uses Joomla’s content system, you will need to create Joomla categories for JReviews listings. Categories will be assigned to a listing type and a directory.

Joomla allows you to create unlimited levels of categories and JReviews provides additional Directory level that can be used to group similar categories. Here is an example of a directory page:

Creating at least one directory is required, but you don't need to show the directory page on your site if you don't want to. The advantage of the directory page is that it can display the complete category tree (all levels of categories), unlike category pages which can only show direct subcategories.

Examples of directories can be found on the JReviews demo site (every top level menu item in the Top Menu is a directory page):

Business Directory

City Guide

Products Catalog

Movies

Games

Music

Downloads

Classifieds

Events

Even though the demo site has many directories (to show different types of sites you can create with JReviews), most sites need just one directory.

The only reason why you might need to create more than one directory is if your site will have categories that are completely unrelated to each other (i.e. business categories and product categories).

Directories that you create will need to be assigned to categories in the JReviews Categories Manager.

1.2.3 Using JReviews Custom Fields for additional categories

Even though Joomla allows you to create unlimited number of categories and unlimited levels of categories, it is not recommended to create a large number of categories as that can make the overall site setup too complex and time consuming (i.e. creating required menu items for every category).

We recommend to create a small number of Joomla categories and extend those categories with JReviews virtual categories.

The virtual categories are actually values of JReviews custom fields. For certain single select or multiple select custom fields you can enable the Click2Search setting and then each field value of that field becomes a virtual category.

Some of the advantages of virtual categories are that new virtual categories can be added "on the fly" during the listing submission and one listing can have multiple virtual categories (both is not possible with Joomla categories).

A good example of using virtual categories is for restaurant's cuisines. You can create a multiple select custom field "Cuisines" and enable Click2Search so that that field values become virtual categories. When visitors click on a certain cuisine, they will get a list page with all listings that have the same cuisine. Examples of virtual categories can be found on the JReviews demo site:

Italian Cuisine

American (New) Cuisine

Japanese Cuisine

For more info read How to use custom fields as virtual categories.

1.3 JReviews Submit Forms

Information is entered into JReviews via the Listing, Review and Media forms:

The Listing form - for submitting listings (articles).

The Review form - for submitting editor or user reviews and ratings (or comments only).

The Media form - for submitting media items (photos, videos, attachements, audio files) to listings or reviews.

Listings and reviews can be submitted only via the frontend of your site. There are two ways to access the submit form:

Create a "Submit New Listing" JReviews Menu Item.

Enable the "Add new listing" button in the configuration so it appears at the top of every Category list page.

The Review form is available to listing detail pages, so that visitors viewing the listing can submit their reviews.

You can also enable the review form to be displayed together with the listing form, if you want to enable users to submit listings and reviews at the same time.

The Media form will appear as a second step after listing or review submissions. You can also enable "Add Media" button for listing detail pages so that users can easily add photos at any time.

1.3.1 Listing submit form

The Listing form contains the following elements:

Title

Title alias - available only to administrators (aliases are used for urls).

Listing custom fields - fields that you create for a specific listing type.

Summary - standard joomla field, it can be made optional or disabled in the configuration. Has support for wysiwyg editor.

Description - standard joomla field, it can be made optional or disabled in the configuration. Has support for wysiwyg editor.

Meta Keywords

Meta Description

You can configure which user groups are able to submit certain fields in the JReviews Access Settings.

Example of a listing submit form:

1.3.2 Review submit form

The Review form has the following fields:

Review Title - standard field, can be made optional or disabled in the configuration.

Ratings - rating stars on different criteria you create in Listing Types Manager.

Review custom fields - review fields that you create for a specific listing type.

Comments - standard field, can be made optional or disabled in the configuration.

Example of a review submit form:

1.3.3 Media submit form

The Media form allows uploading photos, videos, attachments, audio files and linking to external videos (Youtube, Vimeo or Dailymotion).

Example of a media submit form:

Chapter 2 Installation & Upgrade

2.1 Downloading the latest JReviews package

To access your license downloads, log in on our website and then go to the Client Area.

If you can't access the client area after log-in and instead you see a message saying you are already logged in you can try using a different browser or use this alternate link to log in.

In the Client Area click the View Your Licenses link on the left menu and then click the View & Download button:

On the next page you will see your license details and available downloads:

You will be able to download the latest version as long as you have a valid upgrades package. You get 12 months of free upgrades. After expiration you need to renew the upgrades if you want to download the most recent version.

2.1.1 Downloading JReviews Add-ons

There is no download link for JReviews Add-ons, they can be installed directly from JReviews administration!

2.2 Pre-install requirements

2.2.1 CMS Requirement

JReviews is compatible with:

Joomla! 2.5

Joomla! 3.2

2.2.2 PHP Requirement

Required PHP version is 5.2.x or higher.

Required PHP Extensions: json, mbstring, curl, bcmatch (most servers have them installed by default).

PHP Configuration:

upload_max_filesize in php.ini must bi higher than 2M (for installation files to upload successfully).

2.2.3 IonCube

IonCube loader needs to be installed and enabled on your server. On some hosting packages it is enabled by default.

If ionCube is not enabled on your server, you can ask your host to install it for you, or you can do that yourself:

Download loaders package from ionCube website.

Upload ioncube_loader_lin_5.3.so file (if your server uses PHP 5.3) or ioncube_loader_lin_5.4.so file (if your server uses PHP 5.4) anywhere in your joomla folder.

Create the /administrator/php.ini file and add this line (use the correct path to the ioncube file where you uploaded it):

zend_extension=/path/to/ioncube/folder/ioncube_loader_lin_5.3.so

Note: If you are having troubles installing ioncube, download loader-wizard.zip file, extract the zip and place the loader-wizard.php file into the root of your site. Run that file and it will guide you through the installation process.

Watch a "How to check JReviews pre-install requirements" video tutorial on YouTube

2.3 Installing JReviews

First extract the JReviews package that you downloaded from the Client Area (package_jreviews_2.4.x_unzip_first.zip).

This is the folder structure of the package:

/apps_easysocial - installation files for JReviews apps for EasySocial integration

/modules - installation files for all JReviews modules

/plugins_community_builder - installation files for CB plugins

/plugins_everywhere_addon - installation files for Everywhere add-on plugins

/plugins_jomsocial - installation files for JomSocial plugins

com_jreviews_2.4.zip - JReviews component installation file

com_s2framework_1.5.zip - S2 Framework installation file

2.3.1 Installation Steps

Make sure that the Joomla debug mode is disabled in Joomla global configuration, system tab.

In the Joomla Administration click on Extensions -> Extension Manager menu.

In the Install tab click Browse and locate the S2Framework component package - com_s2framework_1.5.zip.

Click the Upload & Install button.

After the S2 Framework is installed, click Browse again and locate the JReviews component package - com_jreviews_2.4.zip.

Click Upload & Install.

Next you'll see a link Click here to continue with the installation.

After the installation is finished, you'll get a Click here to go to the component page link.

On the next screen enter your License Number.

Click Submit and JReviews is ready to use.

JReviews modules and plugins will be installed automatically.

2.4 Upgrading JReviews

2.4.1 What happens to my existing listings, reviews and customizations when I upgrade

Upgrading JReviews does not remove your configuration settings, or any of your existing data such as listings and reviews. These are stored in the database and the upgrades affect mostly the file system. If an upgrade requires database changes, then this is automatically taken care of by JReviews. If you've made any theme or code changes, you should make a backup of your modified files before proceeding with the upgrade.

2.4.2 Remote Upgrade

You can do a one-click remote upgrade by using the Install & Update menu in the JReviews administration under the Maintenance header on the left column:

Always upgrade the S2Framework first and JReviews second.

Remember to backup any files you've customized inside /components/com_jreviews/ because they will be replaced during the upgrade. You can use the JReviews Code Overrides to move the files outside the core folders to prevent them from being overwritten.

We recommend that you use a development server to test the upgrade first and that you rename the jreviews_overrides folder to something else and clear the file registry before you upgrade.

2.4.2.1 The upgrade doesn't work, what now?

Enable FTP Layer in Joomla Global Configuration and try again. If that doesn't help, use your FTP client to temporarily modify the permissions of the Joomla /tmp folder to 777 and do the same with the components' administrator and frontend folders. For example /administrator/components/com_jreviews and /components/com_jreviews.

You can also use the regular upgrade method described below.

2.4.3 Manual Upgrade

If you are upgrading your production server it's always a good idea to perform a full backup of your site, including database and files, in case you need to revert the upgrade. A useful Joomla extension for this is Akeeba Backup.

Backup your JReviews theme and other files if you made changes to them. It is not necessary to do this if you are using JReviews Code Overrides feature to put modified files outside the /components/com_jreviews folder.

Go to the Joomla Extensions Manager and uninstall both S2Framework and JReviews components.

Install new versions of S2Framework and JReviews Component.

Re-upload your modified JReviews theme files (only if you are upgrading from a minor release, otherwise your old theme files might not be up to date).

Clear the browser cache! Otherwise you may end up with non-working links.

2.4.3.1 Upgrading to JReviews 2.4 from earlier versions

Since this is a major version upgrade it won't be possible to upgrade remotely from earlier JReviews versions. Once you install JReviews 2.4 you'll be able to continue using the remote updater.

Create a development site first to test the upgrade. You can use website cloning tools like Akeeba Backup for this purpose.

Uninstall GeoMaps and PaidListings add-ons via Install & Update page in JReviews administration.

Remove any overrides. You can do this quickly by renaming the whole 'jreviews_overrides' folder to something else. Never rename this folder back to 'jreviews_overrides' because you will break JReviews. You can't use any old JReviews 2.2 or JReviews 2.3 files with the new JReviews 2.4 version.

Uninstall the S2Framework and JReviews components.

Download the package from the client area, your upgrades need to be valid or you need to order a new upgrades package.

Install the new S2Framework and JReviews and CLEAR the browser cache.

If you have a GeoMaps, PaidListings or WidgetFactory license, install them from the remote installer in JReviews and CLEAR the browser cache.

Go to the JReviews remote installer and install the Image Migrator add-on and then follow the instructions. You need to setup the storage settings for photos in JReviews Media Settings before you run the migrator.

2.4.3.2 Troubleshooting a broken upgrade

The most important thing to do when an upgrade presents broken functionality is to test the same function without any theme or code changes. If you use the code overrides functionality, you should rename the jreviews_overrides folder and clear the file registry. If the issue is solved, it means you need to update your modified files to bring them up to date with their most recent versions.

If you have made any theme or code changes read What happens with modified files when JReviews is upgraded

Chapter 3 Setting up JReviews

3.1 Creating Joomla categories

JReviews uses Joomla's content system, so the first step in setting up JReviews is to create Joomla categories that will contain JReviews listings. Examples of different category structures can be seen on the directory pages of the JReviews demo site:

Business Directory

City Guide

Products Catalog

Movies

Games

Music

Downloads

Classifieds

Events

Joomla makes it possible to create unlimited levels of categories and JReviews supports this (listings would be created in last level categories).

It is recommended to create categories similar to the examples on the demo site. Avoid creating too many categories as that can make the overall site setup too complex and time consuming (i.e. creating required menu items for every category).

Keep in mind that listings within specific categories can be additionally filtered using JReviews custom fields (more info about that later).

If you plan to create a City Guide type of site, it is not recommended to create cities as Joomla categories. Instead, create a single select type of custom field in JReviews that would have cities as options to select when submitting or searching listings.

3.1.1 Creating Categories

To create categories, go to the Joomla administration area click on Content -> Category Manager menu.

Click New in the toolbar:

Enter the Title of the Category, other fields are not required. If you are creating a subcategory, then select a parent category. If you write something into the Description text area, it will be displayed as page description on the JReviews Category pages.

Click Save & New and repeat the process until you create all categories that you want. Click Save & Close after you create the last category.

Categories will later be assigned to JReviews listing types and directories.

3.2 Creating Custom Field Groups

3.2.1 About Field Groups

One of the main advantages of JReviews listings over Joomla articles is the ability to have additional fields besides standard Title, Summary and Description fields.

Field Groups allow you to "categorize" those additional custom fields by grouping them together. For example, a Contact field group will contain fields such as address, phone number and email.

There are two types of field groups:

Listing Field Groups - for listing submit forms

Review Field Groups - for review submit forms

Field groups can be re-used across different listing types. For example, you can use your Contact field group in a Hotel listing type and also in a Restaurant listing type. And you can also assign more than one field group to each listing type.

Creating field groups and custom fields is optional and you can create them later at any time.

3.2.1.1 Listing Field Groups

A Listing field group will group listing custom fields, which are used to structure the entry and display of information of your listings.

Here is an example of a listing submit form:

On the screenshot you can see the default Joomla fields + additional JReviews listing field groups that contain custom fields:

Location - contains custom fields about listing location. This field group would be reused for many listing types (i.e. Hotels, Restaurants, Local Businesses, ...)

Hotel Info - this field group contains fields for more info about the hotel and it would be used only for hotel listings.

Contact Info - contains contact information. This field group would also be reused for many listing types.

Other Examples of listing field groups:

Product Info - for product listings, it would contain fields like product brand, model and other product features.

Event Info - it would contain fields like event date and event venue.

3.2.1.2 Review Field Groups

A Review field group will group review fields, which are used to structure the entry and display of information in user and editor reviews. Review fields are mostly used to ask reviewers for their experience with the listing they are reviewing. You can also ask users for information about themselves, so that others reading their reviews know whether the reviewer is similar to them.

Here is an example of a review submit form:

On the review submit form you can see several standard review fields like Title and Comments, rating criteria (more about this later) and a single review custom field group named Travel Details which we use to ask hotel reviewers more info about their stay at the hotel.

Other Examples of review field groups:

Product Experience - ask product listing reviewers for pros and cons of the product they are reviewing.

About Me - ask reviewers about their age or age range, interests, level of expertise, etc.

Companies Services - ask reviewers if they are satisfied with the company's services or products.

3.2.2 Steps to create Field Groups

Click on the Field Groups Manager menu link in JReviews administration.

Choose whether you are creating a Listing field group or Review field group by selecting Listing or Review in the Location select list.

Enter the title of the field group into the Title input and click the Add button:

When you are done creating field groups, you can go to the Fields Manager to create custom fields for them.

3.2.3 Controlled Field Groups

It is possible to have field groups that are controlled by values of a specific custom field. The controlled field group will be hidden on the submit form and it will appear only when the user selects its parent custom field value.

For example, if you have product listings on your site and you want to have a separate set of custom fields for a specific product type, you would first create a Product Type custom field (with options like Laptops, Tablets, etc.) in the Product Info field group and then create a separate field group Laptop Info that would appear on the submit form only when Laptops value is selected in the Product Type custom field.

To create a controlled field group, go to the Field Groups Manager. enter the title of the field group and enter the field name and field value in the Control Field and Control Value inputs:

3.3 Creating Custom Fields

After you created field groups, go to the Fields Manager to create custom fields for those fields groups.

To create a Listing custom field, select Listing for the Location on the top left corner and click New on the top right corner. To create a Review custom field select 'Review' for the Location and click New.

After you click New, you will be taken to the Field creation screen. Most of the field settings are optional. To quickly create a field, enter the Title, Type and Field Group (Name will be generated automatically) and click the Save button:

3.3.1 Field settings

These are the common field settings that are available for most types of custom fields:

Title - this is a label that will be displayed next to the field input on submit forms and next to the field value on listing pages.

Name - name is used for database reference only. JReviews will append "jr_" as name prefix when the field is saved. You will use the field's name in the theme files, if you want to modify the default layout and placement fields.

Type - each of the field types is explained separately below.

Maximum Characters - limits the number of characters allowed for this field. It is important to set this number, otherwise the number of the custom fields that you will be able to create won't be large. For example, if you are creating a City custom field, enter the maximum number of characters that a single city could have (i.e. 30). For multiple select and checkbox fields keep in mind that the selected options are all stored in the same input so the length should accomodate all the selected options and would be longer than your typical single and radio button fields.

Field Group - each custom field can be assigned to a single Field Group.

Required - if set to Yes, users will not be able to submit a listing unless they enter a value for this field.

Enabled - must be set to Yes, otherwise it's as if the field doesn't exist.

Show title - shows the field title on listing detail page or list pages. This setting is not used for submit forms.

Show in Detail View - if disabled, the field will not be outputted on listing detail pages. If you want to place the field manually in the theme instead of using the default output, set to No.

Show in List View - shows the field on category, search and other list pages.

Show in Compare View - shows the field on listing comparison pages.

Enable for ordering - shows the field in the ordering dropdown list on list pages.

Click2Search - makes the field value clickable to allow users to find other items with the same value (field values become "virtual categories"), except for the website field.

Control Field - the field will be hidden on the submit form until the control field that you enter here is selected first.

Control Value - if you selected the control field, it is required to select a control value after which the field will show up.

Description - enter the field description for submit forms to provide more info to users regarding what they need to enter as field value. The description can be shown as:

tooltip next to the field title

text above the field input

text below the field input

Submit/Edit Access - only selected user groups will see the field when submitting a new entry or editing an existing one.

View/Search Access - only selected user groups will see or search this field.

Validation Regex - field value that users enter will need to pass the validation based on the regex you enter here. Some field types like website and email have a default regex which prevents them from entering invalid urls or email addresses.

Allow HTML - if enabled, users will be able to enter simple html tags, for example:

<b>Bold Text</b>
<i>Italic Text</i>

Click2Search URL - here you can adjust the url of Click2Search pages. For example, if you want the pages to return listings from the same category instead of from the same listing type, replace criteria:{criteriaid}/ with cat:{catid}/. Available tags are {criteriaid}, {catid}, {optionvalue}, {optiontext}, {fieldname} and {itemid}.

Output Format - here you can adjust the output of the field. The {fieldtext} tag represents the saved field value. If you want to add some custom text next to the field value, add it before or after this tag. To add a value of some other custom fields, use {jr_fieldname} tag (use an actual field name).

Click2search Output Format - this setting is useful if you want to modify the click2search links (i.e. add additional attributes to the link).

Apply Output Format Before Click2Search - if enabled, the modified output format will be included in click2search links as well.

PHP Based Formatting - here you can apply PHP code to the output of the field. Returning boolean false hides the field. Code errors may break the page where the fields are shown. Read more about PHP Based Formatting.

3.3.2 Types of custom fields

Text field

This is a regular text input. Use it when none of the other field types are better for entering a specific value (i.e. when every entry will have a unique value).

Example of the text field on the submit form:

Text area

This is a regular textarea form field. Use it when users are expected to enter a lot of text as field value.

Example of the text area field on the submit form:

Code enabled Text area

The same as regular text area, except it allows entering javascript code. This is useful for affiliate code and various javascript widgets. Important: Only administrators should be allowed to enter values into this field (for security reasons), select only Super User group in the Submit/Edit Access setting.

Email address

The same as regular text field, but with email input validation. The output shows a linked email that opens the user's default email client.

Website url

Text field with website url input validation. The output shows a linked website address that takes the user to that website. This field type has a different default Output Format than other field types:

<a href="{fieldtext}" target="_blank">{fieldtext}</a>

If the urls that users will enter will be very long, you might want to link to display "visit website" instead of the full url. To do that, adjust the Output Format like this:

<a href="{fieldtext}" target="_blank">visit website</a>

Banner field

This field type doesn't accept any user input (it doesn't show up on submit forms). Any text or code that you enter into the Banner Code text area will be displayed together with other fields. This is useful for things that will be identical in every listing (i.e. ads).

Date field

Date field type makes entering date values much easier using the calendar based date picker:

The date field has several additional advanced options:

Date output format - here you can adjust the date format that will be used to display the date to site visitors. Examples of different date format parameters can be found on PHP's strftime function.

Year Range - check the jQuery UI datepicker documentation for options Relative to today's year -nn:+nn, relative to the currently selected year c-nn:c+nn, absolute nnnn:nnnn, or combinations of these formats nnnn:-nn. Leave empty for +-10 from selected year.

Min Date - check the jQuery UI datepicker documentation for options A string in the format defined by the dateFormat option, or a relative date. Relative dates must contain value and period pairs; valid periods are "y" for years, "m" for months, "w" for weeks, and "d" for days. For example, "+1m +7d" represents one month and seven days from today.

Max Date - check the jQuery UI datepicker documentation for options A string in the format defined by the dateFormat option, or a relative date. Relative dates must contain value and period pairs; valid periods are "y" for years, "m" for months, "w" for weeks, and "d" for days. For example, "+1m +7d" represents one month and seven days from today.

Decimal number

This is a text field with decimal numbers input validation. This field type has two additional field options:

Currency Format - if enabled, the field value will be displayed as a currency. To add a currency next to the field value, add it to the Output Format text area before or after the {fieldtext} tag.

Number of Decimals - choose how many decimals will be shown in the field output (for non-currency decimal fields)

Integer number

This is a text field with integer input validation. Keep in mind that this field can store only actual integer numbers without leading zeroes. It is not good for phone numbers and similar, use the text field type instead.

Single select list

This is a standard "dropdown" field that allows users to select a single value.

Example of the field on the submit form:

This type of field requires that you create field options that will be offered to users for selection. To create field options, you can click the Field Options button when editing the field:

or click on the + button in the Options column next to the field in the Fields Manager:

On the next screen you will get see a form for creating field options:

Text is what will be visible to users. Value is a database reference and it must be all lowercase and without spaces or specia characters. Image (optional) allows you to enter a name of the image that will be displayed instead of the field text in the field output. The image needs to be placed inside the /theme_images directory of the JReviews theme that you selected in JReviews configuration. You'll need to click on Clear Cache & File Registry link under Maintenance menu in JReviews administration for JReviews to recognize any images you uploaded to /theme_images.

After you populate the required Text and Value, click the Add button in the top right corner to create the field option.

The Single select list field type has additional settings:

Use Auto Complete UI - if enabled, the dropdown will be converted to an autocomplete text input for selecting a value. This is useful if you plan to have a large number of options for the field. Users would need to type-in first few letters of the value to select it:

Click2Add - this setting is useful if you want to allow adding new options to the select list directly on the submit forms. Otherwise, users would only be able to select field options that you created in the Field Options Manager.

Show option images - if disabled, text will show on field value output even if images are assigned to field options.

Option ordering - Use A-Z to order the field options inside the select list alphabetically, or User defined order for options to be ordered based on the ordering in Field Options Manager.

Multiple select list

This field works the same as the single select list, except it allows users to select more than one field options. Example of the field on the submit form:

This field type also requires field options to be created and has all the same settings as the single select field.

Checkboxes

Checkboxes field type is an alternative to multiple select field type for selecting multiple field options:

The type of the field can be switched from multiple select to checkboxes and vice versa at any time. One of the differences between them is that it is not possible to add more checkboxes on the submit form, all field options must be created in the Field Options Manager.

Radio buttons

Radio buttons field type is an alternative to single select field type for selecting a single field option:

The type of the field can be switched from single select to radiobuttons and vice versa at any time. It is also not possible to add more radio button options on the submit form, all field options must be created in the Field Options Manager.

Related Listing

This field type doesn't have field options. Instead it allows users to select an exiting listing as the value:

The output of this field will be a link that will point to that listing.

This field is useful for parent -> child field relations. For example, if you have listings for events and venues, you could use this field type in event listings to select a parent venue listing.

Note: This field type allows selecting a single listing only.

Available options for this field type are:

Listing Type Filter - select the listing types that will be used to filter the listing suggestions shown for this field.

Current user only - limits suggestions to listings owned by the current user. Editors and above will get suggestions for all listings.

3.4 Listing Types

3.4.1 About listing types

After you created field groups and custom fields, the next step is to define the listing types that will include those field groups. Examples of listing types you might create:

Business - a type of listing that will include field groups (fields) like Location (City, Address, Postcode), Contact Info (Phone number, Email address, Website url), etc.

Hotel - this listing type would include Location and Contact Info field groups the same as business listing type, but it can also include additiona Hotel Info field group with fields like Hotel Amenities, Pricing, etc.

Restaurant - similarly to hotels and businesses, this listing type would include Location and Contact Info field groups as well, but you can also create additional field group(s) for entering information about restaurant's Cuisine and Menus.

Product - this type of listing would have a Product Info field group with fields like Brand, Model, Release Date, Product Website, etc.

Movie - a type of listing that would include a field group with information about the movie (Year, Directors, Actors, Genre) and a field group with affiliate links where visitors can buy/rent movies (Amazon, iTunes, Netflix)

Event - it would contain event information fields like Event Date and Event Venue.

In the listing types you also need to define rating criteria for User/Editor reviews. You could add just a single Overall Rating criterion or you would create multiple rating criteria and the overall rating will be automatically calculated as average of individual criteria. Examples:

Hotels would be rated for Service, Location, Pricing

Products would be rated by Features, Performance, Value for money

Movies would be rated by Story, Actors performance, Cinematograpy, Soundtrack

Listing types will be assigned to categories in the JReviews Categories Manager. They can be assigned to any number of categories. For example, if you are building a local business directory, you probably created many categories for different types of businesses like Contractors, Home Services, Auto Repair, Accounting, etc., and for all those categories you would assign the same Business listing type. But the Hotels listing type would be assigned just to a single Hotels category.

When planning your listing type setup consider this:

if you need the same listing/review submit forms (with the same field groups and rating criteria) for multiple categories, create a single listing type for those categories

if some categories need different field groups or different rating criteria, create a separate listing type for them

3.4.2 Creating listing types

To create a listing type, go to the Listing Types Manager in JReviews administration and click the New button in top right corner. On the next page you will get the listing type creation screen:

Main Settings

Title - enter the listing type title.

Comments & Ratings - 3 options are available:

Allow comments and ratings

Allow comments without ratings

Disable comments and ratings - useful for News and other listing types that don't require comments or ratings.

Select all the field groups you want to associate to this listing type - choose listing and review field groups for this listing type.

Display in Advanced Search Page - the advanced search page displays a list of listing types for users to choose from to search by their custom field values. Here you can disable the specific listing type from showing up on the advanced search page.

Rating Criteria

Rating Criterion - enter the title of the rating criterion

Required - uncheck if you want the criterion to be optional.

Weight - criteria weights for weighted average rating calculation. The total must add to 100, do not enter the % character. If left blank a simple average will be calculated.

Tooltip - hints for users on how to rate in the review form.

Example of a listing type:

3.4.2.1 Configuration overrides

Every listing type has its own settings which override the global settings:

3.4.2.2 SEO Manager

Use the SEO Manager in listing types to define custom title and meta tags for listing detail pages:

SEO Manager enables you to easily customize page title, meta keyword and meta description for each listing type so that they change dynamically based on section, category and custom fields.

Tags that you can use

Listing title - {title}

Directory title - {directory}

Category title - {category}

Summary text - {summary}

Description text - {description}

Meta description - {metadesc}

Meta keywords - {metakey}

Custom fields - {jr_fieldname} (i.e. jr_brand)

For example, if the title of a listing is "Affinia Dumont", the default title tag would look like this:

<title>Affinia Dumont</title>

If you set custom tags for title like in the screenshot above, the title tag would look like this:

<title>Affinia Dumont - New York Hotel Reviews</title>

The same way you can customize the Meta description and Meta Keywords tags.

You can use any combination of tags and your custom text.

3.4.2.3 Detail Page Widgets

Detail page widgets allow you to show related listings in the detail page of listings. For example, on a hotel detail page, you could publish a widget that would show "Nearby hotels", "Hotels in the same city", etc.

Here is an example of how the widget would look like:

3.5 Directories

3.5.1 About directories

Directories are used to group similar categories. Examples of directories can be found on the JReviews demo site (every top level menu item in the Top Menu is a directory page):

Business Directory

City Guide

Products Catalog

Movies

Games

Music

Downloads

Classifieds

Events

Even though the demo site has many directories (to show different types of sites you can create with JReviews), most sites need just one directory (and at least one directory is required).

The only reason why you might need to create more than one directory is if your site will have categories that are completely unrelated to each other (i.e. business categories and product categories).

Directories that you create will need to be assigned to categories in the JReviews Categories Manager.

3.5.2 Creating Directories

To create a directory go to the Directories Manager in JReviews administration.

Enter the directory Title (will be displayed on the site) and Name (reference value, all lowercase without spaces or special characters) and click the Add button:

3.6 Assigning Joomla categories to listing types and directories

The final step of JReviews setup is to go to the Categories Manager to assign a listing type and a directory to each Joomla category that you want to use with JReviews.

Click the Setup New button and a popup will appear:

First select a listing type and a directory then choose all categories that will belong to that listing type and directory and click the Save button.

Important: If you created multiple levels of categories, it is imporant to include all of them (both parent and child categories), but for parent categories choose This category will not have listings instead of a listing type. Only last level categories should have a listing type assigned. Also, all levels of categories must belong to the same directory (a subcategory must belong to the same directory as its parent category).

If you made a mistake with the category assignment, you can remove the category by clicking on the X button at the and of the category row:

After you remove the category, you will be able to set it up again, but removing the categories will be possible only until listings in those categories will have reviews.

When you complete your JReviews setup, it is necessary to adjust the configuration settings and to create JReviews menu items.

Chapter 4 Configuring JReviews

4.1 Configuration Settings

JReviews Configuration Settings are divided into different tabs:

4.1.1 General

Debug PHP & Queries - shows PHP and Database debug information at the bottom of the page. This is useful when you have an error on one of the JReviews pages, but you get a blank page. Enabling this will allow you to see the error messages.

Debug Themes - shows the theme output of each theme labeled with the theme filepath as well as the controller filename and function is used to process the output.

Debug IP - limits debug output to this IP address only. Click Insert IP button for JReviews to enter your IP address.

Read more about Theme debug tools

Disable Overrides - ignore all files in the overrides folder. If you made code customization in the jreviews_overrides folder and something stops working on the site, use this setting to test if the bug is coming from your customizations. The Debug IP setting above has no effect over this setting which runs for all site visitors.

Disable DB Query Index Hints - by specifying index hints in certain DB queries it is possible to improve their performance. In some setups the index hints have a counter effect and disabling the feature allows MySQL to find a better index.

Include language segment in Ajax URI - setting only relevant for multilingual sites. Disable if ajax requests fail on non-default languages.

Load All Minified - most 3rd party javascript libraries are already minified by default. By enabling this setting all proprietary JReviews files will also load minified to improve loading time.

Enable Javascript Loader - loads scripts in parallel and non-blocking to speed up the page rendering process.

Disable jQuery - jQuery is not optional. If you disable it, make sure it is loaded by your template or a plugin (i.e. jQuery Easy).

Disable jQuery UI - jQuery UI is not optional. If you disable it, make sure it is loaded by your template or a plugin (i.e. jQuery Easy).

Joomla style URL parameters - uses the &param=val style for url parameters rather than /param:val. It is recommended to leave this enabled.

Disable Secure URLs when site accessed via SSL - useful for add-ons that render site links on remote sites with secure URLs. This only works for URLs rendered by JReviews.

Display 'Results per page' - disabled by default to avoid duplicate pages for SEO.

Security image verification - enables captcha for guests and/or registered users, used in submission listing, review and review discussion forms.

Create accounts for guests - guests will be given the option to enter a username when making a submission to automatically create an account for them. This feature requires that email activation in Joomla is enabled so users can receive an email with a temporary password.

Use username or realname - choose which will be displayed on the site.

Site theme - this is the main theme that will be used for the JReviews frontend. If you will create a custom theme, this is where you'd select it.

Mobile theme - here you can choose a theme that will be used on smartphones. It is recommended to select the same theme that you selected for Site theme. The Default Theme is responsive and works fine on mobile devices by default. The only reason why you might want to use a separate mobile theme is if you want to delete certain page elements only for smartphones. JReviews includes a Mobile Theme that you can use for this purpose.

Fallback theme - all theme files that the selected Site theme doesn't have will be loaded from the fallback theme. The Default Theme should always be selected here (unless JReviews will have two different fallback themes in the future).

Number of items per page - used for pagination.

Number of pages shown in pagination in lists - number of pages between the first and last page.

Show Breadcrumb - adds a pathway on top of JReviews' category and detail pages.

Override CMS breadcrumb in detail page - takes over the article page breadcrumb showing JReviews links.

4.1.2 Cron

Running the JReviews cron url is required for maintenance purposes (rebuilding ranks and purging cache). If Run Cron on site visits is enabled, it will run automatically by JReviews when required. If you have a large site, it is recommended to disable this and instead setup a cron job on your server using the url from Cron url.

4.1.3 Community

Community - choose a community extension from which JReviews will automatically show user avatars and create links to user profiles from listings and reviews.

Services - choose which social media buttons will be shown on listing and media detail pages. Output can be modified in /jreviews/views/helpers/community.php file.

Button Count Position - choose between horizontal or vertical social media buttons.

Disable Secure URLs - useful if you use both secure and non-secure URLs on your site to avoid having duplicate URLs for social sites.

Here you can choose on which actions JReviews will send activities to JomSocial or EasySocial.

If you use JomSocial, make sure you enable the JReviews Activity Stream plugin in the Joomla Plugin Manager.

If you use EasySocial, enable JReviews Activity Stream app in EasySocial Applications Manager.

Here you can enable auto tweets for submissions of new listings, reviews or review comments.

Read the Twitter integration article for more info.

The Facebook integration allows users to post their submissions to their FB wall. This is possible only for unmoderated submissions (i.e. those automatically published). Moderation of submissions can be disabled in Access Settings.

Read the Facebook integration article for more info.

It is recommended to set Enable Open Graph Protocol to Yes for better functionality of the Facebook like button.

4.1.4 Directory

Show alphabetical index bar - if enabled, the directory page will show an alphabetical bar like this:

Display category images - here you can choose to show images next to categories if you assigned them in Joomla Category Manager. Applies to top level categories only.

Number of columns - choose in how many columns the categories will be displayed on the directory page. This is possible only if you have more than one top level categories.

Show number of entries per category - if enabled, the number of listings will be shown next to each category. Also applies to the category box in lists.

Hide empty categories - categories without listings will not be shown. Also applies to the category box in lists.

Category levels to show - choose how many levels of categories to show.

Categories format - choose between Bullet list and Comma separate list. When comma list is selected only 2 level of categories are shown.

4.1.5 List page

Theme Layout - available options:

Tableview - displays listings in a table (not recommended for sites with responsive design)

Blogview - standard layout similar to "blog posts"

Thumbview - displays listings in 4 columns per row. This layout requires that all listings have the same height.

Masonry - displays listings in columns automatically based on the thumbnail dimensions. Advantage over Thumbview layout is that listings/thumbnails can have different heights, disadvantage is that javascript is used to resize the layout. It is recommended to enable 'scale' thumbnail mode for list pages in Media Settings.

Show 'Add new listing' button in category pages - the button will be shown only to last level categories (those that have a listing type assigned) and only to users that are allowed to submit listings to those specific categories.

Use current page Itemid in the 'Add new listing' url - if enabled, the 'Add new listing' page will display the same modules as the category page.

Show listings of child categories - if enabled, parent categories will display listings of child categories (subcategories).

Enable listing comparison - if enabled, listings will display a Compare button/checkbox. Checked listings will appear in the comparison dashboard after which users will be able to compare them.

Slider listing columns - how many listings users will see on the comparison page before they'll need to use the slider.

Show detailed user ratings - if enabled the individual criteria ratings will be shown.

Show detailed editor ratings - if enabled the individual criteria ratings will be shown.

Show categories in CATEGORY list view - list of sub-category links shown at the top of the category page.

Number of columns for categories - choose in how many columns the sub-category links will be shown.

Show ordering dropdown list - if enabled, the ordering dropdown list will be shown on every category page.

Default Ordering - choose default ordering.

Order by field - this setting overrides the default ordering. Use jr_field or rjr_field for descending order. You should use this setting only if the field you are using is common across all listing. Otherwise you should use the equivalent setting in the listing types.

Choose which listing information will be displayed. Average User Rating is only for list pages and other settings are for listing detail pages as well.

Show summary - here you can enable showing the summary text on list pages.

Trim summary (words) - choose how many words of the summary text will be shown. If zero or blank it will display all the text. Limiting the number of words will strip all html formatting.

The Label settings are used on both list and listing detail pages.

Action Box settings are for the list pages only.

4.1.6 Listings

Enable favorites - if enabled, users will be able to add listings to their favorites list

Enable Listing Claims - if enabled, users will be able to claim listings to become owners of the listing and to be able to edit listing details. Any claim submission must be approved by admins in JReviews administration.

Enable claims only for listings owned by (optional) - add user ids separated by comma without any spaces. If you are adding most listings yourself you can enable the claims functionality only for your userid or setup a special user to submit listings and make them claimable.

Limit the number of characters shown - if you enter the number of characters higher than 0, visitors will need to click the 'show more' link to expand the full text. Limiting the number of characters will strip all html formatting.

Enable Listing Inquiries - this enables a Send Inquiry button on listing detail pages for site visitors to be able to fill a contact form to request information. If you want to embed the form directly on the page, leave this setting disabled and instead add this code to the theme file of the listing detail page (/listings/detail.thtml):

<?php echo $this->element("inquiry_widget");?>

Inquiry is sent to - choose who will receive the email from site visitors:

Listing owner - the e-mail will be sent to the e-mail address of the person that submitted the listing.

Site e-mail - the e-mail will be sent to the e-mail address set in Joomla configuration.

Custom field e-mail - the e-mail will be sent only if the listing has a value in the e-mail custom field specified in the below setting.

Custom field name - if custom field selected above, enter the field's name here (i.e. jr_email).

BCC Admin email - a copy of the e-mail will be sent to this e-mail address.

4.1.7 Reviews

View All Reviews Canonical (SEO) - outputs a canonical tag to the listing detail page in the view all reviews page for a listing (to avoid Google considering the "view all reviews" page as a duplicate of the listing detail page).

Enable User Reviews - if enabled, users will be able to review listings.

Enable Editor Reviews - available options:

One editor review per listing

Multiple editor reviews per listing - this option will allow multiple multiple editor reviews by different users. It is not possible for a single user to submit more than one editor review.

No editor reviews

Comma list of JReviews Editors user IDs - only reviews written by these users will be automatically recognized as editor reviews. Addittionaly, any review can be marked as an editor review in the review moderation menu.

Multiple user reviews per listing - valid for registered users only. Checking is done against IP address and userid.

Disable IP address check for multiple reviews - performs check on user id only.

Stop users from reviewing their own listings - also disable the review form in listing submission in Configuration => Standard Fields.

Default Ordering - choose how reviews will be ordered:

Most Recent

Oldest

Last Updated

Highest user rating

Lowest user rating

Most helpful

Least helpful

Most discussed

Rating scale - enter a number higher than zero. Once you have reviews on your site DO NOT change this setting.

Rating increment - choose between 0.5 and 1.

Rating selector in review form - choose between Star Images and Select List.

Pre-select N/A for optional rating criteria - if enabled, users don't need to click on the N/A option to ignore a criterion.

Hide non-rated criteria from detailed ratings - useful if there are many optional criteria.

Show rating count in detailed ratings - this can be informational when users gave N/A ratings to certain criteria.

Enable listing owner replies to user reviews - listing owners will be able to reply to reviews.

Enable review discussions - a 'Comments' button will appear in every review that will take users to a separate review detail page where they'll be able to discuss the review.

Enable reporting of user reviews - if enabled, every user review will display a "report review" icon in bottom right corner. All reports will be sent to the JReviews administration area.

Enable reporting of editor reviews - if enabled, every editor review will display a "report review" icon in bottom right corner. All reports will be sent to the JReviews administration area.

Enable user review voting - if enabled, visitors will be able to vote on review helpfulness.

Enable editor review voting - if enabled, visitors will be able to vote on review helpfulness.

Disable ip address check for votes - by default, JReviews will prevent visitors from voting multiple times. Here you can disable IP address check (for testing purposes).

Settings for editor reviews.

Settings for user reviews.

4.1.8 Standard Fields

Allow duplicate listing titles - you should not enable duplicate listing titles in the same category if you are removing ID numbers from listing urls via the JReviews SEF Plugin.

Name - (Required | Optional | Hidden) - not shown to registered users

E-mail - (Required | Optional | Hidden) - not shown to registered users

Summary - (Required | Optional | Hidden)

Description - (Required | Optional | Hidden)

Review form shown to - choose who will be able to submit a review when submitting a new listing.

Make review optional - shows a checkbox allowing users to hide the review form when submitting a new listing.

Title - (Required | Optional | Hidden)

Name - (Required | Optional | Hidden) - not shown to registered users

E-mail - (Required | Optional | Hidden) - not shown to registered users

Comment - (Required | Optional | Hidden)

4.1.9 Search

Use current page Itemid for search results - works only for JReviews pages, not detail pages which are com_content. In that case the JReviews search menu id will be used or one you specify below.

Specify a menu id for search results - used in detail pages; and other JReviews pages if the setting above is disabled.

If one result found, redirect to detail page - disable to always show the search results page.

Allow all listings to be returned with empty search queries

Theme Layout - available options:

Tableview - displays listings in a table (not recommended for sites with responsive design)

Blogview - standard layout similar to "blog posts"

Thumbview - displays listings in 4 columns per row. This layout requires that all listings have the same height.

Masonry - displays listings in columns automatically based on the thumbnail dimensions. Advantage over Thumbview layout is that listings/thumbnails can have different heights, disadvantage is that javascript is used to resize the layout. It is recommended to enable 'scale' thumbnail mode for list pages in Media Settings.

View Suffix - if you want to use a different theme file for the search results page (i.e. listings_blogview_search.thtml), enter the suffix here.

Default query type - 'Any' will look for listings which contain any of the words. 'All' will look for listings that contain all the words.

Show search box in listings and directory - simple search will be displayed on directory and category pages.

Use current page category id as filters for simple search - if enabled, the search input on a category page will return listings only from that category.

Allow searching by listing owner - displays the author input field to allow searching for listings written by a specific user.

Allow searches on more than one option for single select and radiobutton fields - allows searches that match several options for single select and radiobuttons. For example: if you have a multiple select field with all the states in the US, the user will be able to choose several of the states instead of just one if this setting is disabled.

4.1.10 Notifications

Choose which e-mails will be sent to admins.

Choose which e-mails will be sent to users.

To customize the text of the emails you need to edit the email themes in this folder:

/components/com_jreviews/jreviews/views/themes/default/email_templates/

4.1.11 RSS

If feeds are enabled, one feed icon will be displayed in the listing detail page for user/editor reviews of that listing and two feed icons will be displayed in list pages (one for listings and one for user/editor reviews).

4.1.12 Cache

Cache Settings - cached files will be re-created if they have expired.

Enable query cache

The cache is cleared after the duration time has passed or every time the JReviews setup, configuration, and a listing or review is submitted or updated. This setting, when enabled, caches the data returned from the database for both guests and registered users. It reduces the number of queries per page for lists and detail pages, which have some of the most intensive queries.

Notes: The cached queries will take up disk space because all returned data is stored. If disk space is an issue, monitor it and it might make sense to leave it disabled. It's a trade-off between database queries and disk storage. To get improved results for registered users, query cache should be used in combination with a view cache solution where view cache is typically disabled in both JReviews and Joomla.

Enable view cache (Guests only)

Caches whole views for guest users only. The cache is cleared after the cache duration time has ended or every time the JReviews setup, configuration, and a listing or review is submitted or updated.

Notes: This setting is similar to the Joomla Cache. The JReviews view cache is only for guests viewing the output of the JReviews component, not the entire site. If you are using the Joomla Cache or a 3rd Party Cache, it may be best to turn off this cache.

Enable session cache

Caches data to the user's session to reduce the number of queries. For example the total count of results for different paginated pages is cached and then read from the user's session data.

Notes on JReviews Cache Optimization in General:

If you enable debug mode in Joomla you can check the number of queries and memory used in the different pages, and that gives you a reference for what happens when you enable/disable some of these settings. When using another extension to compress JS or CSS files you may have to exclude some of the JReviews scripts from the optimization. After optimizing your sites be sure to check all functionality as a guest.

4.2 Media Settings

4.2.1 Display Settings

Force use of Catch-All menu for media urls - you need to create the JReviews Catch-All menu item for Media. If disabled, JReviews category menu ids will be used if they exist.

No Image Path - enter the path to the default image. For the default image to appear on listings, also enable Use Default Image setting.

Video Processing Path - enter the path to the default image for videos when they are still processing.

Thumbnail Quality - choose the quality of the generated thumbnails in a scale from 1-100. Default is: 85.

Default Media Order - this is the ordering that will be used in media list pages.

Default Media Order - Listing Specific - this is the ordering that will be used in listing detail pages and photo and video galleries for a specific listing. If you choose Ordering, the media items will be ordered based on how you ordered them on the 'Media Edit' page of a specific listing.

Display Terms & Conditions in upload page - users will need to accept your Terms & Conditions when submitting media items if this setting is enabled. The terms will not display for the Joomla editor group and above.

Add additional link to Submission Guidelines page - enter the Joomla Article ID of the Terms & Conditions articles that you want to use. You can find the ID in the Joomla Article Manager.

Choose which media count icons will be displayed on list and listing detail pages.

Show Main Media Thumbnail - enable or disable displaying the main media thumbnail on list pages (category pages, search results, etc.).

Thumbnail Mode - (Scale | Crop)

Thumbnail Size - WIDTHxHEIGHT in pixels. This can be considered as "maximum width" and "maximum height" for the thumbnail.

Use Category Image - if main media thumbnail doesn't exist, an image assigned to the category in Joomla Category Manager will be displayed.

Use Default Image - if main media thumbnail doesn't exist, the default image will be used. Set the path to the default image in the No Image Path setting.

Separate Listing Owner and User uploaded media - for photos and videos only. Listing Owner media displays in main area of the listing detail page while Review media will appear in individual reviews. Links to view 'All', 'Listing' and 'Users' photos and videos will also be displayed unless lightbox or gallery layouts are used.

Photo Display Layout - available photo layouts:

Contact sheet with lightbox

Contact sheet linked to separate gallery page

Full width gallery without lightbox

Small gallery with lightbox

Film Strip with lightbox

Film Strip linked to separate gallery page

Video Display Layout - available video layouts:

Contact sheet with lightbox

Contact sheet linked to separate gallery page

Full width video player

Film Strip with lightbox

Film Strip linked to separate gallery page

Audio Downloads - displays a download button next to each track.

Main Media Thumbnail - if disabled, the main media will be displayed in the gallery together with other images.

Disable Main Media Link - disable the lightbox for photos when set as main media. Gallery photos will continue opening in a lightbox if Photo Lightbox is enabled. Useful when company logos are used as main media.

Main Media Thumbnail Mode - (Scale | Crop)

Main Media Thumbnail Size - WIDTHxHEIGHT in pixels. This can be considered as "maximum width" and "maximum height" for the thumbnail.

Show category/default image using above settings for List Pages - if enabled, the listing detail page will display the default image or category image when main media isn't available.

Thumbnail alignment - display the main media on left or right side of the listing detail page.

Gallery Thumbnail Mode - (Scale | Crop)

Gallery Thumbnail Size - WIDTHxHEIGHT in pixels. This can be considered as "maximum width" and "maximum height" for the thumbnail.

Display photo info as overlay on mouseover - when Full width gallery without lightbox is used, you can choose to display photo info on gallery overlay.

Photo Limit - after this number visitors need to go to the gallery page for the listing to view all photos.

Video Limit - after this number visitors need to go to the gallery page for the listing to view all videos.

Gallery Thumbnail Mode - (Scale | Crop)

Gallery Thumbnail Size - WIDTHxHEIGHT in pixels. This can be considered as "maximum width" and "maximum height" for the thumbnail.

Photo Limit - after this number visitors need to go to the gallery page for the listing to view all photos.

Video Limit - after this number visitors need to go to the gallery page for the listing to view all videos.

Media List Layout - choose the layout for media list pages (i.e. Latest Media, My Media)

Thumbnail Mode - (Scale | Crop)

Thumbnail Size - WIDTHxHEIGHT in pixels. This can be considered as "maximum width" and "maximum height" for the thumbnail.

4.2.2 Photos

Replace filename with listing title - if enabled, the uploaded photo filename will be replaced with listing title.

Prepend listing id to filename - if enabled, listing id will be prepended to the photo file name.

Max Photos per Listing per User - choose how many photos each user will be able to upload per listing. Leave blank for no limit. Set to zero to disable uploads.

Max Photos per Review per User - choose how many photos each user will be able to upload per review. Leave blank for no limit. Set to zero to disable uploads.

Maximum Upload Size

Allowed File Extensions - enter the list of allowed photo file extensions, separated by commas.

Original Resize - the uploaded photo will be resized to the specified dimension if larger. Leave blank for no resizing. Default is: 800x800.

Original Resize Quality - choose the quiality of the resized photo in a scale from 1-100. Default is: 90.

4.2.3 Videos

Replace filename with listing title - if enabled, the uploaded video filename will be replaced with listing title.

Prepend listing id to filename - if enabled, listing id will be prepended to the video file name.

Video Upload Methods - available options:

Upload & Link from video sites - users will be able to upload video files and embed videos from other sites.

Upload only - users will be able to only upload videos without embedding videos from other sites.

Link only - users will be able to only embed videos from other sites.

Video Link Sites - choose from which sites embedding videos will be allowed.

Max Videos per Listing per User - choose how many videos each user will be able to upload or embed per listing. Leave blank for no limit. Set to zero to disable uploads.

Max Videos per Review per User - choose how many photos each user will be able to upload or embed per review. Leave blank for no limit. Set to zero to disable uploads.

Maximum Upload Size

Allowed File Extensions - enter the list of allowed video file extensions, separated by commas.

4.2.4 Attachments

Replace filename with listing title - if enabled, the uploaded attachment filename will be replaced with listing title.

Prepend listing id to filename - if enabled, listing id will be prepended to the attachment file name.

Max Attachments per Listing per User - choose how many attachments each user will be able to upload per listing. Leave blank for no limit. Set to zero to disable uploads.

Max Attachments per Review per User - choose how many attachments each user will be able to upload per review. Leave blank for no limit. Set to zero to disable uploads.

Maximum Upload Size

Allowed File Extensions - enter the list of allowed atachment file extensions, separated by commas.

4.2.5 Audio

Replace filename with listing title - if enabled, the uploaded audio filename will be replaced with listing title.

Prepend listing id to filename - if enabled, listing id will be prepended to the audio file name.

Max Audio per Listing per User - choose how many audio files each user will be able to upload per listing. Leave blank for no limit. Set to zero to disable uploads.

Max Audio per Review per User - choose how many audio files each user will be able to upload per review. Leave blank for no limit. Set to zero to disable uploads.

Maximum Upload Size

Allowed File Extensions - enter the list of allowed audio file extensions, separated by commas.

4.2.6 Storage Settings

Photos - choose between Local or Amazon S3 storage.

Videos - videos can only be uploaded to Amazon S3 (because they need to be encoded into multiple formats by 3rd party video encoders).

3rd Party Videos (embedded) - choose between Local or Amazon S3 storage for thumbnails of embedded videos.

Attachments - choose between Local or Amazon S3 storage.

Audio - audio files can only be uploaded to Amazon S3 (because they need to be encoded into multiple formats by 3rd party audio encoders).

Path: - choose where media files will be uploaded when Local storage is enabled. Default is: media/reviews/

Original media folder name - choose the subfolder name for the original uploaded media.

Thumbnail media folder name - choose the subfolder name for the thumbnails.

API Key - if you choose to store media files to Amazon S3, enter the API Key of your Amazon S3 account.

API Secret - if you choose to store media files to Amazon S3, enter the API Secret of your Amazon S3 account.

Replace Amazon S3 URLs with CDN URLs - if you want to use CloudFront CDN with Amazon S3, read how to set up JReviews with Amazon S3 and CloudFront CDN.

4.2.7 Encoding Settings

Encoding Service - if you enabled video or audio uploads, you need to have an account with one of the 3 available encoding services that will encode video/audio to all required formats:

Transloadit.com

Encoding.com

Zencoder.com

Video Frame Size - choose the video frame size. Default is 854x480.

Bitrate - choose the bitrate for encoded video/audio files.

Transfer Method - this method will be used by the encoding service to download the uploaded files from your server. The S3 method uploads the file from your server to S3 to let the encoding service download it from S3. If you choose ftp make sure your server allows enough simultaneous connections.

Enter your account details for one of the encoding services.

4.3 Access Settings

4.3.1 Listings

Submit New Listing - select user groups that will be allowed to submit listings.

Moderate new listing - new listings submitted by selected user groups will be held for approval by admin.

Moderate edited listing - listings will be unpublished and held for approval when edited via the frontend.

Edit listing - choose which user groups will be able to edit listings. Registered and Author can edit only their own listings. Editor and above can edit all listings, but only see custom fields for which they have access.

Publish/unpublish listing - select users groups that will be allowed to pulbish/unpublish listings. Registered and Author can only publish/unpublish their own listings.

Delete listing - select users groups that will be allowed to delete listings. Registered and Author can only delete their own listings.

WYSIWYG editor - select user groups that will have a WYSIWYG editor enabled for standard summary and description text areas. JReviews will use the WYSIWYG editor that is selected in Joomla Configuration. Supported editors are TinyMCE and JCE.

Meta data fields - select user groups that will be able to enter Meta Keywords and Meta Destription data when submitting listings. This is not necessary if you setup automatic meta data via the Listing Type Manager.

4.3.2 Reviews

Submit new review - select user groups that will be allowed to submit reviews.

Moderate new user reviews - new user reviews submitted by selected user groups will be held for approval by admin.

Moderate new editor reviews - new editor reviews submitted by selected user groups will be held for approval by admin. Define JReviews editors in Configuration => Reviews tab. These are not Joomla editors.

Moderate edited user reviews - user reviews will be unpublished and held for approval when edited via the frontend.

Moderate edited editor reviews - editor reviews will be unpublished and held for approval when edited via the frontend.

Enable voting - select user groups that will be allowed to vote reviews helpful.

Edit review - choose which user groups will be able to edit reviews. Registered and Author can edit only their own reviews. Editor and above can edit all reviews, but only see custom fields for which they have access.

4.3.3 Media

Here you can select default View Access Level for Listings and Reviews Media. Only the selected access level will be able to view/play/download media. The media count totals will reflect the count for media that is not accessible to the current user. This is because totals are pre-calculated for improved performance.

Allow Uploads from URL - selected user groups will be able to upload listing media by pasting the url to the media file on a 3rd pary site.

Photos/Videos/Attacments/Audio - select user groups that will be able to add media to listings.

Registered Group - select All to allow uploads by any registered user without the need to submit a review.

Allow Uploads from URL - selected user groups will be able to upload review media by pasting the url to the media file on a 3rd pary site.

Photos/Videos/Attacments/Audio - select user groups that will be able to add media to reviews.

Moderate (Hold for approval) - media uploads of selected user groups will be held for approval by admin.

Edited Media - media will be sent back to the moderation queue and held for approval when edited via the frontend.

Likes for Photos - select user groups that will be allowed to like/dislike photos.

Likes for Videos - select user groups that will be allowed to like/dislike videos.

Edit Media - choose which user groups will be able to edit media items. Registered and Author can edit only their own media. Editor and above can edit all media.

Delete Media - choose which user groups will be able to delete media items. Registered and Author can delete only their own media. Editor and above can delete all media.

Publish Media - choose which user groups will be able to publish media items. Registered and Author can publish only their own media. Editor and above can publish all media.

4.3.4 Discussions

New Comment - select user groups that will be allowed to comment reviews. (Review discussions need to be enabled in Configuration Settings => Reviews).

Moderate (Hold for approval) - New Comment - comments of selected user groups will be held for approval by admin.

Edit Comment - choose which user groups will be able to edit comments. Registered and Author can edit only their own comments. Editor and above can edit all comments.

Delete Comment - choose which user groups will be able to delete comments. Registered and Author can delete only their own comments. Editor and above can delete all comments.

4.3.5 Owner Replies

Moderate listing owner replies to reviews - listing owner replies to reviews will be held for approval by admin.

4.4 Predefined Replies

If you enabled Moderation of user submissions in Access Settings, here you can predefine E-mail Replies that will be sent to users when you Approve or Reject their submissions.

Predefined e-mail replies are available for Listing, Review, Media, Owner Reply, Discussion Post and Claim submissions.

For each of them you can predefine 5 different replies.

Tags that you can use in your e-mail replies:

{name} = user's name

{url} = frontend url

{listing_title} = listing title

4.4.1 Moderation of submissions

Whenever there are user submissions waiting for approval, you will see the Moderation menu in the sidebar of JReviews administration:

When you go to any of the moderation queue pages to moderate submissions you will be able to Accept, Reject or Hold each submission.

If you click the Choose Predefinied Reply button, a drop down list will appear allowing you to select one of the Predefined Replies that you setup before. The predefined replies can also be edited before sending the e-mail.

4.5 Theme Manager

Theme Manager allows you to easily manage customizations for individual categories in JReviews, including the listing detail pages.

The Theme Manager displays a list of all categories, allowing you to select a different layout (Tableview, Blogview, Thumbview or Masonry) and assign theme file suffixes for each of them. Theme suffixes are explained in more detail below.

For any given page, except for search results, the category theme setup is checked first, then the global setting (List page tab in configuration settings).

When a suffix is assigned (i.e. _museums), you can copy and rename any view/css file to use that suffix. If the file is found, it will be used, otherwise the default view/css files are used.

Example:

/listings/detail.thtml - original detail page theme file

/listings/detail_museums.thtml - modified file that will be used only for listings that belong to the Museums category.

After adding new files to your JReviews theme, you must always click the Clear Cache & File Registry link in the JReviews Administration so JReviews can recognize the new files:

4.5.1 Theme suffixes in menus and modules

You can also have different theme files for JReviews Menu items and Modules.

For the Menu Items, you can specify different theme suffix in the menu item's preferences.

For the Modules, you can specify different theme suffix in the module's preferences.

4.6 Fields SEO Manager

The Fields SEO Manager allows taking advantage of Click2Search pages by adding title and meta tags that can be indexed by search engines.

The Click2Search feature for custom fields can be enabled in the Fields Manager. It links the field text to a results page with listings that have the same field value.

For example, if you have a "Brand" custom field and you enable Click2Search, when a user clicks on certain brand (i.e. Sony), he would be redirected to a page with all Sony listings. With the SEO Manager, you can add Meta Title, Meta Keywords and Meta Description tags to those Click to Search pages.

You can use the {fieldvalue}, {category} and {parent_category} tags in the title, keywords and description fields if you want the value of the field to be shown in the text in the front end. The category tags will work only if you modify the Click2Search urls for each field to use the 'cat' parameter instead of 'criteria'.

Show page title at the top of the list - if enabled, what you enter as Meta Title will be displayed at the top of the Click2Search pages.

Show meta description at the top of the list - if enabled, what you enter as Meta Description will be displayed at the top of the Click2Search pages (below the title).

Example:

If you have Book listings on your site and created an "Author" custom field with Click2Search enabled, when users click on a certain author, they will be taken to a page with a list of all books written by that author.

If you enter "Books written by {fieldvalue}" as the Meta Title for that custom field, the title of the Click2Search page when users click on book author (i.e. 'Dan Brown') will be: "Books written by Dan Brown".

4.7 Category SEO Manager

The meta keywords and description displayed below are the same ones stored in the Joomla Category Manager. Here you can quickly view and edit them. You can also add a custom page title and override the page heading and page description for category pages.

The following tags can also be used: {category} - current category title, {category1}, {category2}, etc. which represent the titles of parent categories of the current category. {category1} is the first level, {category2} the second level and so on.

Chapter 5 Menu Items & SEF

5.1 Creating Required Joomla Category Menu Items

All listings and articles in Joomla must have a parent menu item, otherwise their URLs have ugly "/component/content/article/" segment and it is not possible to assign modules to those pages.

Without a parent menu item, the listing URL will look similar to this:

example.com/component/content/article/49-category-name/subcategory-name/305-listing-title

JReviews uses Joomla's content system for listings and because of this the parent menu item of listings must be a Joomla Category Blog/List menu item. After you create those menu items, the "/component/content/article/" segment in URLs will be replaced with the titles of category menu items.

Starting with JReviews 2.4.10 version, those Joomla Category menu items can be used as the main navigation of your site if you enable the JReviews SEF Plugin. In this case, create Joomla Category menu items in the main menu of your site.

If you don't enable the JReviews SEF Plugin, you will need to create required Joomla category menu items in a "hidden" menu that isn't shown on your site and for the main menu of the site create separate JReviews Category List menu items.

5.1.1 Creating required category menu items

5.1.1.1 How to choose the best category menu item structure

Choosing a good menu item structure is important because the title aliases of those menu items will be used in URLs of listings. You have a choice:

create menu items only for top level categories

create menu items only for last level categories

create menu items for all categories

The third option is recommended because then none of the category URLs will have ID numbers and urls will include the full category structure.

5.1.1.2 Steps for creating the menu items when JReviews SEF plugin is used

in Joomla administration go to the main menu of your site where you want to display the Categories and click the New button in the toolbar.

next click the Select button and you will get this popup with the list of available menu item types, choose Category Blog or Category List (it is not important which one):

after you click on the menu type, you will need to choose a category from the dropdown.

after you created menu items for all categories, go to JReviews administration and click on the "Clear Cache & File Registry" link in the left menu. This is necessary because JReviews stores a cached version of the menu system to improve performance.

With this setup, you will have a "perfect" URL structure, for example:

example.com/category-name
example.com/category-name/subcategory-name
example.com/category-name/subcategory-name/listing-title

5.1.1.3 Steps for creating the menu items when JReviews SEF plugin isn't used

in the Joomla administration click on Menus => Menu Manager and to create a new menu click on New.

in the next screen enter the Title and Menu Type:

after the Hidden Menu is created, click New in the toolbar to create the first menu item.

next click the Select button and you will get this popup with the list of available menu item types, choose Category Blog or Category List (it is not important which one):

after you click on the menu type, you will need to choose a category from the dropdown.

after you created menu items for all categories, go to JReviews administration and click on the "Clear Cache & File Registry" link in the left menu. This is necessary because JReviews stores a cached version of the menu system to improve performance.

With this setup, the listing URLs will include the category names that you created in this Hidden Menu, for example:

example.com/category-name/ID-listing-title

The categories will have a separate URL structure based on how you create JReviews Category List menu items in the main menu of your site.

5.2 Creating JReviews Menu Items

For users to be able to submit and access content, it is required to create some of the many menu items that JReviews provides.

To create a menu item, go to one of your Menus in the Joomla Menu Manager and click the New button:

On the next page, click the Select button to select the type of menu item:

A popup with all menu item types will appear:

Click on a link to create a specific type of a menu item. Each menu type is explained below.

Whenever you edit an existing JReviews menu item and adjust its parameters, you need to go to the JReviews administration and click the "Clear Cache & File Registry" link for the changes to be applied.

5.2.1 Advanced Search

The Advanced Search menu item allows visitors to search listings based on multiple field values.

Example of the advanced search menu item can be found on the JReviews demo site http://demo.reviewsforjoomla.com/search.

The Advanced Search menu item has these parameters:

Listing Type - if you leave the listing type unselected, visitors will first need to select a listing type on the advanced search page before the search form will expand with all fields. If you select a specific listing type, the adv. search page will automatically expaned all custom fields available for that listing type.

Theme suffix - here you can choose a theme suffix for the search results page.

By default, all custom fields that are included in a specific listing type will appear on the advanced search page. If you want to hide specific fields from appearing on the search form, you can do it in the Fields Manager:

Important: it is required to have a least one advanced search menu item without a listing type selected for JReviews search functionality to work correctly. If you don't want to show the advanced search page on your site, you can create this menu item in a "Hidden Menu" that isn't displayed on the site.

5.2.2 Catch-All options

Some types of JReviews pages don't require a regular JReviews menu item, which means it's not easy to controll their URL structure or to assign modules to them. To solve this problem, it is recommended to create Catch-all menu items that will automatically become the parent menu items of those pages.

The Catch-All options menu item has these parameters:

Type of Menu - there are 4 different options, which means you should create a separate menu item for each of them:

Media - parent menu item for all media detail pages and media upload page.

Listing Edit - parent menu item of all listing edit pages

Listing Comparison - parent menu item of all listing comparison pages

View All Reviews for Listing - parent menu item of all "View All Reviews" pages that are available on listing detail pages when the listing has a large number of reviews.

Everywhere Extension - this parameter is used only when "View All Reviews for Listing" type of menu is used. You can have a separate "View All Reviews" menu item for each Everywhere Extensions. For JReviews listings always use 'com_content'.

The Catch-All menus should not be visible anywhere on your site, you should create them in a "Hidden Menu".

5.2.3 List Pages

List pages display a list of listings based on how you configure the menu parameters.

The List Pages menu item has these parameters:

Type of Menu - available options:

Category List - if you don't use the JReviews SEF Plugin, it is recommended to create this type of menu item for every single category. With the JReviews SEF Plugin enabled this type of menu item isn't necessary.

Top User Rated - displays highest user rated listings

Top Editor Rated - displays highest editor rated listings

Most Recent - displays latest listings

Most Popular - displays listings with the highest number of views

Most Reviews - displays listings with the highest number of reviews

Featured - displays only featured listings. Listings can be made Featured on the Browse Listings page in JReviews administration or via the "Manage" dropdown in listing details on frontend.

My Listings - displays listings of the logged in user. Should be created in a "User menu" that isn't visible to guest visitors.

My Favorites - displays listings that the logged in user added to his favorite list. Should be created in a "User menu" that isn't visible to guest visitors.

Custom List - displays listings based on the custom sql commands that you enter in the Custom WHERE and Custom ORDER BY parameters. Read about Custom WHERE and Custom ORDER BY.

Directory - filters listings to the selected directory. This parameter is optional for all types of menus.

Category - filters listings to the selected category. This parameter is required for Category List type of menu and optional for others.

Page total - total number of listings that will be shown.

Limit per page - how many listings will be shown per page.

List layout - if you don't select a specific layout, the one selected in Global Configuration or Theme Manager will be used.

Theme Suffix - enter a theme suffix if you want a different theme file to be used on this page. For example, enter '_compact' to load listings_blogview_compact.thtml theme file instead of the default listings_blogview.thtml file.

Custom WHERE for Custom List only - this parameter is used only if Custom List is selected as type of menu. Read about Custom WHERE and Custom ORDER BY.

Custom ORDER BY for Custom List only - this parameter is used only if Custom List is selected as type of menu. Read about Custom WHERE and Custom ORDER BY.

Page Description - custom description that will appear on top of the page.

5.2.4 Comparison Page

The Comparison Page will display specific listings using the side-by-side layout where visitors can easily compare listing details.

The Comparison Page menu item has these parameters:

Listing IDs (comma list) - it is required to enter the IDs of listings that you want to show on this page. You can find out listing IDs on the JReviews Browse Listings page in administration or in Joomla Article Manager.

Theme suffix - enter a theme suffix if you want a specific theme file to be used for this page.

Page Description - custom description that will appear on top of the page.

5.2.5 Directory

The Directory page is used to display all categories that you use with JReviews. The advantage of the directory page over regular category pages is that the directory page can display all levels of categories. The directory page can't display listings.

Example of a directory page can be seen on the JReviews demo site: http://demo.reviewsforjoomla.com/business-directory.

The Directory menu item has these parameters:

Directory - if you leave this parameter unselected, the page will display all directories. If you select a specific directory, only that one will be displayed.

Theme suffix - enter a theme suffix if you want a specific theme file to be used for this page.

The directory menu item has additional Configuration Overrides parameters:

These parameters will override the settings from the global JReviews Configuration, Directory tab, but only if you set Enable Overrides to Yes.

Remember to click the "Clear Cache & File Registry" link in JReviews administration whenever you edit this menu item and adjust its parameters.

5.2.6 Discussions

The Discussions page will display latest review comments if you enabled them in JReviews Configuration, Reviews tab.

The Discussions menu item has these parameters:

Limit per page - how many results will be shown per page.

Theme suffix - enter a theme suffix if you want a specific theme file to be used for this page.

5.2.7 Media Pages

The Media pages display media items (photos, videos, attachments, audio files) based on how you configure the menu parameters.

Example of a "Latest Media" page can be seen on the JReviews demo site http://demo.reviewsforjoomla.com/latest-media.

The Discussions menu item has these parameters:

Type of Menu - available options:

Media List - dispays all media items based on the below parameters.

My Media - displays media items submitted by the logged in user. Should be created in a "User Menu" that isn't visible to guest visitors.

Order - choose how the media items will be ordered (Newest | Oldest | Most liked | Most viewed).

Show Order List - if set to Yes, users will be able to reorder media items.

Media Type - choose All to show all types of media or only a specific type.

Show Media Type Filter if set to Yes, users will be able to filter media items by type.

Extension - filter media items by component.

Description - custom description that will appear on top of the page.

Show Description - choose to show or hide the description.

Page total - total number of media items that will be shown.

Limit per page - how many media items will be shown per page.

Theme suffix - enter a theme suffix if you want a specific theme file to be used for this page.

5.2.8 Submit New Listing

The Submit New Listing menu item will display the listing submission form. Users will first need to select the category where they want to submit the listing and then the rest of the form will appear.

Only users that are allowed to submit listings based on the JReviews Access Settings will see the submit form.

The Submit New Listing menu item has these parameters:

Directory - if you select a directory, users will be able to submit listings only to categories that belong to that directory.

Category - if you select a category, users will be able to submit listing only to the selected category (and its subcategories if they exist).

Theme suffix - enter a theme suffix if you want a specific theme file to be used for this page.

5.2.9 Reviewer Rank

The Reviewer Rank page displays the list of users based on the number of reviews they had written and the percentage of helpful reviews.

Example of a Reviewer Rank page can be seen on the JReviews demo site: http://demo.reviewsforjoomla.com/reviewers-rank.

The Reviewer Rank menu item has these parameters:

Limit per page - how many users will be shown per page.

Theme suffix - enter a theme suffix if you want a specific theme file to be used for this page.

5.2.10 Reviews Pages

The Reviews pages display a list of reviews based on how you configure the menu parameters.

Example of a "Latest Reviews" page can be seen on the JReviews demo site: http://demo.reviewsforjoomla.com/latest-reviews.

The Reviews Pages menu item has these parameters:

Type of Menu - available options:

My Reviews - displays reviews of the logged in user. Should be created in a "User Menu" that isn't visible to guest visitors.

Reviews - Latest reviews (all) - displays latest user and editor reviews.

Reviews - Latest user reviews - displays only latest user reviews.

Reviews - Latest editor reviews - displays only latest editor reviews.

Reviews - Custom List - displays reviews based on the custom sql commands that you enter in the Custom WHERE and Custom ORDER BY parameters. Read about Custom WHERE and Custom ORDER BY.

Category - filters reviews to the selected category. This parameter is optional. If the Category is selected, you must enter the Extension name in the below parameter.

Extension - use to filter reviews by component (i.e. com_content, com_sobi2).

Page total - total number of reviews that will be shown.

Limit per page - how many reviews will be shown per page.

Theme Suffix - enter a theme suffix if you want a specific theme file to be used for this page.

Custom WHERE for Custom List only - this parameter is used only if Reviews - Custom List is selected as type of menu. Read about Custom WHERE and Custom ORDER BY.

Custom ORDER BY for Custom List only - this parameter is used only if Reviews - Custom List is selected as type of menu. Read about Custom WHERE and Custom ORDER BY.

Page Description - custom description that will appear on top of the page.

5.3 SEF URLs

Due to the number of Search Engine Friendly (SEF) url solutions and the work required to support them we have decided to only officially support three of them: Core Joomla SEF, sh404sef and SEF Advance. If you decide to use a different solution we won't be able to provide support for it.

We recommend using Core Joomla SEF which we think provides very good results without adding too much overhead and have several articles below explaining what you need to do to make sure it works well with JReviews. Core Joomla SEF combined with JReviews SEF Plugin allows to have perfect category and listing URL structure without using any 3rd party SEF extensions.

5.3.1 Using Joomla Core SEF

To make the URLs look nicer, you should enable Joomla core SEF:

go to Joomla Global Configuration, and on first tab set Search Engine Friendly URLs and Use URL rewriting to Yes.

leave Add Suffix to URLs disabled.

go to the root folder of your site and rename htaccess.txt file to .htaccess if you don't already have the .htacess file. This is required for URLs to work when Use URL rewriting is enabled.

5.3.2 Using JReviews SEF Plugin

Starting with JReviews 2.4.10 version, JReviews installation includes a SEF plugin which makes it possible to render Joomla category pages as JReviews category pages allowing you to simplify the menu and SEF URL structure and to improve the URLs of listings by removing the ID numbers from URLs.

Important:

the JReviews SEF plugin is not compatible with other 3rd party SEF extensions. You can't use it together with sh404sef, SEF Advance or any other SEF extension.

when using the SEF plugin with the article ID removal feature, you must not allow duplicate listing titles in the same category. Check your settings in the JReviews Configuration, Standard Fields tab. If you have listings with duplicate titles, then you need to change the title aliases so they can have different URLs.

The plugin is automatically installed, but it is left unpublished. After you read the instructions below, you can publish the plugin in the Joomla Plug-in Manager.

These are the plugin options:

Remove Article ID from URL - if enabled, URLs of listing detail pages will no longer have ID numbers and the SEF plugin will automatically 301 redirect old listing URLs with ID numbers to new URLs without ID numbers. This option should not be enabled if you allow submissions of listings with the same title in the same category.

Use core Category menus - if enabled, JReviews will render Joomla category menu items as JReviews category pages which means it is no longer required to create a separate JReviews Category List menu items. If you already have JReviews Category List menu items, they will be redirected to Joomla Category menu items when this setting is enabled.

Use JReviews Category Menu ID - if your site already has JReviews category menus which are visible to site visitors, enabling this will allow those menus to appear as active menus when clicked.

Replacement for URLs without Itemid - all JReviews pages without an Itemid (parent menu item) will use this string in URL instead of the default /component/jreviews/ segment.

New listing submission segment - appended to category URLs for new listing submissions.

View all reviews segment - appended to view all reviews URL when not using a catch-all menu item.

View all photos segment - appended to view all photos URL when not using a catch-all menu item.

View all videos segment - appended to view all videos URL when not using a catch-all menu item.

Search results segment - appended to search URL.

5.3.2.1 Recommended setup of menu items when JReviews SEF plugin is used

For new sites

Create only Joomla Category List or Category Blog menu items. Either for all categories, or only for top level or last level categories. It is recommended to create them for all categories so that none of the category urls have ID numbers.

Those Joomla Category menu items are supposed to be used as the main navigation of the site and they will be rendered as JReviews category pages. It is not necessary to create separate JReviews Category List menu items.

The URLs of categories will follow the menu item structure. For example, if you created a category menu item as first level menu item, it will look like this:

example.com/category-menu-alias

For subcategories, it is recommended to create menu items as a child of the parent category menu item, then the URL will look like this:

example.com/category-menu-alias/subcategory-menu-alias

The URLs of listings will look like this:

example.com/category-menu-alias/subcategory-menu-alias/listing-title-alias

If you want to include a directory name in the URL structure, create a JReviews Directory menu item and make it a parent of Joomla category menu items, then the URL will look like this:

example.com/directory-menu-alias/category-menu-alias/subcategory-menu-alias/listing-title-alias

If you have a lot of subcategories and don't want to create menu items for all of them, you can create menu items only for top level categories and then the URLs will contain subcategory names with ID numbers, for example:

example.com/category-menu-alias/ID-subcategory-name/listing-title-alias

For old sites that already have urls indexed by search engines

Before JReviews SEF plugin existed, it was required to create Joomla category menu items in a "hidden" menu. Those menu items are still required, but with the JReviews SEF plugin the URL structure generated by these Joomla menu items can be used for JReviews Category pages when Use core Category menus is enabled in SEF Plugin parameters.

Basically, you don't need to make any changes to your existing menu item setup, JReviews SEF plugin will automatically apply Joomla category URL structure to JReviews category pages and setup 301 redirects.

Important: You should not delete or rename your existing Joomla category menu items because that will change the URLs of listings and the SEF plugin will not be able to redirect old listing URLs to new ones. If you decide to change your menu item structure, you will need to manually setup 301 redirects from old urls to new ones via the htaccess file.

5.3.2.2 Assigning modules to category and listing detail pages

Important: This feature doesn't work if you use Advanced Module Manager. However, this extension provides similar features.

Now that Joomla category menu items are used as parent menu items for both category pages and listing detail pages, any module that you assign to the category menu items will be outputted on both category pages and listing detail pages.

To allow you to hide a specific module in category pages or listing detail pages, JReviews SEF Plugin adds a setting for this to every module in the Module Manager:

Chapter 6 JReviews Modules

JReviews comes with 9 modules and all of them are installed automatically when installing JReviews. To use any of the modules, go to the Joomla Module Manager and publish the module to one of the module positions that your Joomla template provides.

6.1 Listings Module

The Listings Module can be used for displaying:

Latest Listings

Top User Rated Listings

Worst User Rated Listings

Top Editor Rated Listings

Most Reviewed Listings

Random Listings

Featured Random Listings

Popular Listings

Example of the module layout:

6.1.1 Listings Module Parameters

Listings Ordering - choose what the module will display:

Latest Listings (everywhere)

Top User Rated (everywhere)

Worst User Rated (everywhere)

Top Editor Rated (com_content)

Most Reviewed (everywhere)

Random (everywhere)

Featured Random (com_content)

Popular (com_content)

Proximity (com_content) requires GeoMaps Add-on - works only on listing detail pages.

Radius for Proximity Ordering - used if Proximity is selected in Listing Ordering parameter.

Show Distance for Proximity Ordering - used if Proximity is selected in Listing Ordering parameter.

Show Summary - here you can enable displaying listing summary text in the module.

Summary Words - how many words of the summary text to show.

Show Listing Category - here you can enable displaying the listing category.

Comma separated list of custom fields to show (i.e. jr_state,jr_city) - enter the names of custom fields that you want to show in the module.

Show Editor Rating - here you can enable displaying the editor rating.

Show User Rating - here you can enable displaying the user rating.

JReviews Theme Suffix - this suffix will be applied to the module view file and is useful to create multiple instances of the module that have different outputs. Two alternative theme files with suffixes for the Listings Module come by default with JReviews: _slideshow and _vertical.

Show Thumbnail - enable or disable displaying the main media thumbnail.

Thumbnail Position - (Left | Right | Top | Bottom)

Thumbnail Mode - (Scale | Crop)

Size (WIDTHxHEIGHT) - WIDTHxHEIGHT in pixels. This can be considered as "maximum width" and "maximum height" for the thumbnail.

Everywhere Extension - this is a universal module that works not only with core JReviews listings, but also with 3rd party components integrated via the Everywhere Add-on. The module can only display listings from one component at a time, so you need to enter the component's name here (i.e. com_content, com_sobi2, com_k2, etc.)

Category Autodetect - JReviews will try to determine the category id and show only results for that category. If enabled, this setting overrides all the ID settings below it.

Directory IDs (com_content) - filter listings by directory IDs.

Category IDs (everywhere) - filter listings by category IDs.

Listing IDs (everywhere) - display listings based on specific listing IDs.

With Custom WHERE and Custom ORDER BY parameters you can display listings based on the custom sql commands. Read about Custom WHERE and Custom ORDER BY.

Positioning of Pagination - choose the position of slider arrows when the module has multiple slider pages.

Page Transition - choose the transition type for the slider pagination (Horizontal sliding | Vertical sliding | Fade effect).

Enable Slideshow - if enabled, the module will automatically advance slider pages.

Slideshow Interval (sec.) - time between pages in seconds.

Max. number of results - total number of results that will be displayed.

Results per page - how many results will be displayed per slider page. If you enter the same number as for Max. number of results, then the module slider will be disabled and all results will be displayed at once.

Columns - choose how many results per row to show.

Show numbers - adds numbers before each result.

Submitted in past x days - with this setting you can filter the results to use listings submitted in the past x days. The setting works for all modes.

With reviews submitted in past x days - will display listings that had reviews submitted in the past x days.

Review count higher than - filters the results to listings with having at least the defined number of reviews.

Avg rating higher than - filters the results to listings with having at least the defined average rating.

Enable Compare Button - displays the Compare button in listings (only if listing comparison is enabled in global JReviews configuration as well).

6.1.2 Alternative Layouts of the Listings Module

Example of the _slideshow layout:

To use this layout, enter "_slideshow" in the Theme Suffix parameter.

Example of the _vertical layout:

To use this layout, enter "_vertical" in the Theme Suffix parameter.

6.1.3 Customizing the Listings Module

If you want to customize the theme file of the Listings Module, this is its default location:

/com_jreviews/jreviews/views/themes/default/modules/listings.thtml

Before you start customizing the theme files, make sure you read about JReviews Code Overrides functionality and create a custom theme.

There are two alternative theme files for the Listings Module:

/com_jreviews/jreviews/views/themes/default/modules/listings_slideshow.thtml
/com_jreviews/jreviews/views/themes/default/modules/listings_vertical.thtml

To use one of those, enter the theme file suffix in the Theme Suffix parameter. The same way you can create multiple custom copies of the Listings Module theme file. Remember to clear JReviews File Registry when creating new theme files.

6.2 Reviews Module

The Reviews Module can be used for displaying:

Latest Reviews

Most Helpful Reviews

Random Reviews

Example of the module layout:

6.2.1 Review Module Parameters

Reviews Ordering - choose how the reviews will be ordered:

Latest Reviews

Most Helpful

Random

Review Type - choose to show All reviews or only Editor/User reviews.

Title Format - you can use the {listing_title} and {review_title} tags to build your link title output. You can also specify the total number of characters to show (including the ... at the end), by adding the number inside the tag like this {listing_title 10} - {review_title 15}.

Show Review Comments - here you can enable displaying the review comments text in the module.

Trim Comments (# words) - how many words of the comments text to show.

Comma separated list of custom fields to show (i.e. jr_pros,jr_cons) - enter the names of the review custom fields that you want to show in the module.

JReviews Theme Suffix - this suffix will be applied to the module view file and is useful to create multiple instances of the module that have different outputs.

Show Thumbnail - enable or disable displaying the main media thumbnail.

Thumbnail Position - (Left | Right | Top | Bottom)

Thumbnail Mode - (Scale | Crop)

Size (WIDTHxHEIGHT) - WIDTHxHEIGHT in pixels. This can be considered as "maximum width" and "maximum height" for the thumbnail.

Everywhere Extension - this is a universal module that works not only with reviews of core JReviews listings, but also with reviews of 3rd party component listings integrated via the Everywhere Add-on. The module can only display reviews from one component at a time, so you need to enter the component's name here (i.e. com_content, com_sobi2, com_k2, etc.)

Category Autodetect - JReviews will try to determine the category id and show only results for that category. If enabled, this setting overrides all the ID settings below it.

Directory IDs (com_content) - filter reviews by directory IDs.

Category IDs (everywhere) - filter reviews by category IDs.

Listing IDs (everywhere) - display reviews based on specific listing IDs.

With Custom WHERE and Custom ORDER BY parameters you can display reviews based on the custom sql commands. Read about Custom WHERE and Custom ORDER BY.

Positioning of Pagination - choose the position of slider arrows when the module has multiple slider pages.

Page Transition - choose the transition type for the slider pagination (Horizontal sliding | Vertical sliding | Fade effect).

Enable Slideshow - if enabled, the module will automatically advance slider pages.

Slideshow Interval (sec.) - time between pages in seconds.

Max. number of results - total number of results that will be displayed.

Results per page - how many results will be displayed per slider page. If you enter the same number as for Max. number of results, then the module slider will be disabled and all results will be displayed at once.

Columns - choose how many results per row to show.

Show numbers - adds numbers before each result.

6.2.2 Customizing the Reviews Module

If you want to customize the theme file of the Reviews Module, this is its default location:

/com_jreviews/jreviews/views/themes/default/modules/reviews.thtml

Before you start customizing the theme files, make sure you read about JReviews Code Overrides functionality and create a custom theme.

You can create multiple custom copies of the Reviews Module theme file and enter their suffixes in the Theme Suffix parameter. Remember to clear JReviews File Registry when creating new theme files.

6.3 Advanced Search Module

With the Advanced Search Module you can create a customized search form with custom fields of you choice.

Example of the default module layout:

Example of the module layout after adding custom fields:

6.3.1 Advanced Search Module Parameters

JReviews Theme Suffix - this suffix will be applied to the module view file and is useful to create multiple instances of the module that have different outputs. The module comes with one default suffix "_map" which includes the address and radius fields, you should enter this suffix if you use the GeoMaps add-on.

Specify Itemid of JReviews menu for result url - by default the search result page will inherit an Itemid of the JReviews Advanced Search menu item. Here you can override this to a different menu item if you want.

Theme Suffix for search results page - here you can apply a custom theme suffix for the search results page.

Category Autodetect - if category is detected, the category list will display only that category and its subcategories. If enabled, this setting overrides all the ID settings below it.

Directory IDs (comma list) - limits options shown in category list.

Listing Type IDs IDs (comma list) - limits options shown in category list.

Category IDs (comma list) - limits options shown in category list.

Enable Module Theme - this option allows you to add additional custom fields to the module without customizing the module's theme file.

6.3.2 Creating custom search forms with the Advanced Search module

There are two ways to create your custom forms for the Advanced Search Module. The first and simplest one is by using the module settings. The second one requires modifying the module theme file.

6.3.2.1 Customization via module settings

If you choose to use the module settings, head over to the Joomla Module Manager and click on the Advanced Search Module to edit it. You'll find the Theme Customization Settings section towards the bottom of the 'Basic Options'. Change 'Enable Module Theme' to Yes and paste the starter theme code below in the textarea:

<div class="jrFieldDiv jrLeft">
   {category_label}: {category}
</div>

<div class="jrFieldDiv jrLeft">
   {keywords_label}: {keywords}
</div>

<div class="jrFieldDiv jrLeft">
   <button class="jr-search jrButton">
      <span class="jrIconSearch"></span><span>Search</span>
   </button>
</div>

6.3.2.2 Customization via theme editing

This method requires modifying the advanced search module theme file which is located here:

\com_jreviews\jreviews\views\themes\default\modules\advanced_search.thtml

Before you start customizing the theme file, make sure you read about JReviews Code Overrides functionality and create a custom theme.

This is the code that displays default elements of the module:

<div class="jrFieldDiv jrLeft">
  <?php __t("Category");?>: {category}
</div>

<div class="jrFieldDiv jrLeft">
  <?php __t("Keywords");?>: <input type="text" class="jrText" name="data[keywords]" value="<?php echo Sanitize::getString($this->params,'keywords');?>" />
</div>

<div class="jrFieldDiv jrLeft">
   <button class="jr-search jrButton">
      <span class="jrIconSearch"></span><span>Search</span>
   </button>
</div>

If you need multiple advanced search modules, then you also need multiple versions of the file. Use the Theme Suffix setting in the module while also creating copies of the theme files as explained below.

Theme Suffix Examples:

advanced_search_movies.thtml - enter "_movies" as Advanced search theme suffix in the module's parameters.

advanced_search_hotels.thtml - enter "_hotel" as Advanced search theme suffix in the module's parameters.

When you add a new file to JReviews folders, you need to clear the File Registry in JReviews administration.

6.3.3 Adding custom fields to the Advanced Search Module

To add your custom fields into the form, use these tags:

{jr_fieldname} - outputs the field

{jr_fieldname_label} - outputs the field title

For example, to add a jr_brand custom field, you would use this code in the theme file:

<div class="jrFieldDiv jrLeft">
  <?php __t("Category");?>: {category}
</div>

<div class="jrFieldDiv jrLeft">
  {jr_brand_label}: {jr_brand}
</div>

<div class="jrFieldDiv jrLeft">
  <?php __t("Keywords");?>: <input type="text" class="jrText" name="data[keywords]" value="<?php echo Sanitize::getString($this->params,'keywords');?>" />
</div>

<div class="jrFieldDiv jrLeft">
   <button class="jr-search jrButton">
      <span class="jrIconSearch"></span><span>Search</span>
   </button>
</div>

If you use the module settings, the code would look like this:

<div class="jrFieldDiv jrLeft">
   {category_label}: {category}
</div>

<div class="jrFieldDiv jrLeft">
  {jr_brand_label}: {jr_brand}
</div>

<div class="jrFieldDiv jrLeft">
   {keywords_label}: {keywords}
</div>

<div class="jrFieldDiv jrLeft">
   <button class="jr-search jrButton">
      <span class="jrIconSearch"></span><span>Search</span>
   </button>
</div>

{jr_brand_label}: {jr_brand} was added into the default code.

Use the same process to add your other custom fields.

6.4 Directories Module

You can use the Directories module to display the complete directory/category navigation tree.

Example of the module layout:

6.4.1 Directories Module Parameters

JReviews Theme Suffix - this suffix will be applied to the module view file and is useful to create multiple instances of the module that have different outputs. The module comes with one default suffix "_folders" which will add folder icons next to the links.

Directory IDs (optional) - here you can choose to show only specific directories by entering their ID numbers. ID numbers of directories can be found in JReviews Directories Manager.

Show Directory Links - if disabled, the module will hide directory links and show only category links.

6.4.2 Customizing the Directories Module

If you want to customize the theme file of the Directories Module, this is its default location:

/com_jreviews/jreviews/views/themes/default/modules/directories.thtml

Before you start customizing the theme files, make sure you read about JReviews Code Overrides functionality and create a custom theme.

You can create multiple custom copies of the Directories Module theme file and enter their suffixes in the Theme Suffix parameter. Remember to clear JReviews File Registry when creating new theme files.

6.5 Fields Module

The Fields Module shows a clickable list of options for a chosen field. When visitors click on a certain link, they will get a search results page with a list of listings that have that field value.

Example of the module layout:

6.5.1 Fields Module Parameters

Field name (i.e. jr_fieldname) - this parameter is required. Enter the name of the custom field whose field options you want the module to display. Only field types for which you created field options in the Fields Manager can be used.

JReviews Theme Suffix - this suffix will be applied to the module view file and is useful to create multiple instances of the module that have different outputs.

Itemid selection - you can control the itemid used for the field option links so that modules on the current page are seen on the result list or not.

Itemid - used only if you selected Use Itemid below in the above parameter.

Display mode - choose how the field options will be displayed:

Links horizontal

Links vertical

Tags

Dropdown list

Field option ordering - choose how the field options will be ordered.

Limit option text to x chars - here you can set a maximum number of characters that field options will display.

Before text - this text will appear before the list. You can use html tags.

Category Auto Detect - if a category is found for the page, the results will be limited to that category. If no category is found then the module will use the listing type and category settings below if they are set.

Listing Type ID (single value) - limit results to all categories with the same listing type.

Category IDs (comma list) - separate values with comma. Limit results to specified categories. No need to specify listing type id above.

Custom URL parameters - add any other custom search parameters you want. This could be custom field filters (i.e. jr_brand:canon) or custom ordering (order:jr_price).

6.5.2 Examples of Fields Module display modes

Links horizontal

Links vertical

Tags

Dropdown list

6.5.3 Customizing the Fields Module

If you want to customize the theme file of the Fields Module, this is its default location:

/com_jreviews/jreviews/views/themes/default/modules/fields.thtml

Before you start customizing the theme files, make sure you read about JReviews Code Overrides functionality and create a custom theme.

You can create multiple custom copies of the Fields Module theme file and enter their suffixes in the Theme Suffix parameter. Remember to clear JReviews File Registry when creating new theme files.

6.6 Range Module

The Range Module shows a clickable list of numeric range options for a chosen custom field. It is mostly used for Price Range links. When visitors click on a certain link, they will get a search results page with a list of listings that belong to that price range.

Example of the module layout:

6.6.1 Range Module Parameters

Field name (i.e. jr_fieldname) - this parameter is required. Enter the name of the numeric custom field that will be used to performe range searches.

Ranges (0-100+100-200+200-300+300) - enter the numeric ranges in the specified format. The last value without an upper range will be used to show all numbers above that value.

JReviews Theme Suffix - this suffix will be applied to the module view file and is useful to create multiple instances of the module that have different outputs.

Itemid selection - you can control the itemid used for the field option links so that modules on the current page are seen on the result list or not.

Itemid - used only if you selected Use Itemid below in the above parameter.

Display mode - choose how the field options will be displayed:

Links horizontal

Links vertical

Tags

Dropdown list

Option Prefix - use for units, currency, etc.

Option Suffix - use for units, currency, etc.

Range separator - goes in between the numbers in the range.

Before text - this text will appear before the list. You can use html tags.

Category Auto Detect - if a category is found for the page, the results will be limited to that category. If no category is found then the module will use the listing type and category settings below if they are set.

Listing Type ID (single value) - limit results to all categories with the same listing type.

Category IDs (comma list) - separate values with comma. Limit results to specified categories. No need to specify listing type id above.

Custom URL parameters - add any other custom search parameters you want. This could be custom field filters (i.e. jr_brand:canon) or custom ordering (order:jr_price).

6.6.2 Examples of Range Module display modes

Links horizontal

Links vertical

Tags

Dropdown list

6.6.3 Customizing the Range Module

If you want to customize the theme file of the Range Module, this is its default location:

/com_jreviews/jreviews/views/themes/default/modules/range.thtml

Before you start customizing the theme files, make sure you read about JReviews Code Overrides functionality and create a custom theme.

You can create multiple custom copies of the Range Module theme file and enter their suffixes in the Theme Suffix parameter. Remember to clear JReviews File Registry when creating new theme files.

6.7 Media Module

The Media Module can be used for displaying photos, videos, audio files and attachments based on how you configure the module parameters:

Example of the module layout:

6.7.1 Media Module Parameters

Media Type - choose which media type the module will display:

All

Photos

Videos

Audio

Attachments

Media Ordering - choose how the media item swill be sorted.

JReviews Theme Suffix - this suffix will be applied to the module view file and is useful to create multiple instances of the module that have different outputs.

Type - (Scale | Crop)

Size (WIDTHxHEIGHT) - WIDTHxHEIGHT in pixels. This can be considered as "maximum width" and "maximum height" for the thumbnail.

Show Media Type Icon - if enabled, a small icon will be displayed in top right corner of the thumbnail for visitors to know which type of media the thumbnail represents.

Everywhere Extension - if you want to limit results to a specific extension, then enter it here (i.e. com_content, com_virtuemart, com_sobi2, etc.). Only ONE extension at a time!

Display Media Uploaded By - choose if you want to display media uploaded by listing owners, by users or both.

Category Autodetect - filters results for current category.

Directory IDs (com_content) - filter media by directory IDs.

Category IDs (everywhere) - filter media by category IDs.

Listing IDs (everywhere) - display media based on specific listing IDs.

With Custom WHERE and Custom ORDER BY parameters you can display media based on the custom sql commands. Read about Custom WHERE and Custom ORDER BY.

Positioning of Pagination - choose the position of slider arrows when the module has multiple slider pages.

Page Transition - choose the transition type for the slider pagination (Horizontal sliding | Vertical sliding | Fade effect).

Enable Slideshow - if enabled, the module will automatically advance slider pages.

Slideshow Interval (sec.) - time between pages in seconds.

Max. number of results - total number of results that will be displayed.

Results per page - how many results will be displayed per slider page. If you enter the same number as for Max. number of results, then the module slider will be disabled and all results will be displayed at once.

Columns - choose how many results per row to show.

Show numbers - adds numbers before each result.

6.7.2 Customizing the Media Module

If you want to customize the theme file of the Media Module, this is its default location:

/com_jreviews/jreviews/views/themes/default/modules/media.thtml

Before you start customizing the theme files, make sure you read about JReviews Code Overrides functionality and create a custom theme.

You can create multiple custom copies of the Media Module theme file and enter their suffixes in the Theme Suffix parameter. Remember to clear JReviews File Registry when creating new theme files.

6.8 Favorite Users Module

The Favorite Users Module displays a list of users who've added the listing being viewed to their favorites list.

If enabled, the module will display user avatars together with their names. The module works with avatars from EasySocial, JomSocial or Community Builder.

The Favorite Users Module should be enabled only for listing detail pages.

Example of the module layout:

6.8.1 Favorite Users Module Parameters

JReviews Theme Suffix - this suffix will be applied to the module view file and is useful to create multiple instances of the module that have different outputs.

Only users with avatars - users that haven't uploaded their custom avatars will be hidden.

Positioning of Pagination - choose the position of slider arrows when the module has multiple slider pages.

Page Transition - choose the transition type for the slider pagination (Horizontal sliding | Vertical sliding | Fade effect).

Enable Slideshow - if enabled, the module will automatically advance slider pages.

Slideshow Interval (sec.) - time between pages in seconds.

Max. number of results - total number of results that will be displayed.

Results per page - how many results will be displayed per slider page. If you enter the same number as for Max. number of results, then the module slider will be disabled and all results will be displayed at once.

Number of columns - choose how many results per row to show.

6.8.2 Customizing the Favorite Users Module

If you want to customize the theme file of the Favorite Users Module, this is its default location:

/com_jreviews/jreviews/views/themes/default/modules/favorite_users.thtml

Before you start customizing the theme files, make sure you read about JReviews Code Overrides functionality and create a custom theme.

You can create multiple custom copies of the Favorite Users Module theme file and enter their suffixes in the Theme Suffix parameter. Remember to clear JReviews File Registry when creating new theme files.

6.9 Totals Module

Totals Module is a very simple module that displays the total number of listings and reviews.

Example of the module layout:

6.9.1 Totals Module Parameters

Everywhere Extension - if you want to limit results to a specific extension, then enter it here (i.e. com_content, com_virtuemart, com_sobi2, etc.). Only ONE extension at a time!

JReviews Theme Suffix - this suffix will be applied to the module view file and is useful to create multiple instances of the module that have different outputs.

6.9.2 Customizing the Totals Module

If you want to customize the theme file of the Totals Module, this is its default location:

/com_jreviews/jreviews/views/themes/default/modules/totals.thtml

Before you start customizing the theme files, make sure you read about JReviews Code Overrides functionality and create a custom theme.

You can create multiple custom copies of the Totals Module theme file and enter their suffixes in the Theme Suffix parameter. Remember to clear JReviews File Registry when creating new theme files.

Chapter 7 3rd Party Integration

7.1 Community Integration

7.1.1 EasySocial Integration

7.1.1.1 Displaying user avatars in their listings, reviews, comments and linking to their profiles

To show user avatars in their listings, reviews and comments with links to their EasySocial profiles, it is required to enable EasySocial integration in JReviews Configuration::

Example of a user review with avatar and a link to the user profile:

7.1.1.2 Integrating with EasySocial Activity Stream

To integrate with EasySocial Activity Stream, go to the JReviews Configuration (Community tab) and select posts that will be sent to EasySocial:

In the EasySocial Applications page you need to enable the JReviews Activity Stream App. This App is automatically installed by JReviews if it detects EasySocial is already installed. Otherwise you need to get the App from the JReviews download package and install it via the EasySocial Applications installer.

Example of an activity when someone votes on a review:

7.1.1.3 Displaying listings, reviews and favorites of users on their profile pages

JReviews provides 3 EasySocial Apps for user profiles:

MyListings - displays listings submitted by the user

MyReviews - displays reviews submitted by the user

MyFavorites - displays list of user's favorite listings

These Apps are not installed by default. To install them, download the latest JReviews package from the client area and locate these installation files:

/package_jreviews_2.4.x_unzip_first/plugins_easysocial/mylistings.zip

/package_jreviews_2.4.x_unzip_first/plugins_easysocial/myreviews.zip

/package_jreviews_2.4.x_unzip_first/plugins_easysocial/myfavorites.zip

Apps need to be installed using EasySocial Application installer:

After the installation, reload the EasySocial Applications page and publish the plugins.

Click on the Apps to adjust their parameters. Most of the App parameters are the same as those of JReviews Listings and JReviews Reviews modules, but there are 3 important EasySocial parameters that define how the App will display in user profiles:

Default application - if set to Yes, the App will be automatically installed for all users. If set to No, the App will be displayed only in profiles of users that installed it themselves via their profile settings.

Display as - if you choose Widget, the App will be displayed on the main profile page. If you choose Application Canvas, the App will be displayed as a separate page with a link to the App in the user's profile.

Widget Position - if you selected Widget in the previous setting, here you can choose the position of the App in the profile page.

Example of a MyFavorites App displayed in a profile as a widget:

On the same screenshot you can see in the sidebar links to other Apps that have been set to display as Application Canvas.

Example of a MyReviews App outputted as application canvas in user profile:

7.1.1.4 Integrating with EasySocial User Points

If you want users to be awarded with points when they submit listings, reviews, comments or media, it is necessary to import JReviews rules for points. They are automatically installed, you only need to go to the EasySocial's User Points page, click the Discover link and then click the Start Scan button:

Go to the main User Points page and you should see all JReviews rules:

You can unpublish rules that you don't want to use and adjust the number of points that will be awarded.

7.1.1.5 Integrating EasySocial and JReviews Everywhere add-on for profile reviews

With JReviews Everywhere add-on you can have the ability for users to review each other. This integration is shown in the Everywhere add-on manual.

7.1.2 JomSocial Integration

7.1.2.1 Displaying user avatars in their listings, reviews, comments and linking to their profiles

To show user avatars in their listings, reviews and comments with links to their JomSocial profiles, it is required to enable JomSocial integration in JReviews Configuration:

Example of a user review with avatar and a link to the user profile:

7.1.2.2 Integrating with JomSocial Activity Stream

To integrate with JomSocial Activity Stream, go to the JReviews Configuration (Community tab) and select posts that will be sent to JomSocial:

Next, go to the Joomla Plugin Manager and enable the JReviews Activity Stream plugin. This plugin is automatically installed by JReviews if it detects JomSocial is already installed. Otherwise you need to get the plugin from the JReviews download package and install it via the Joomla Extension installer.

Example of an activity when someone votes on a review:

7.1.2.3 Displaying listings, reviews and favorites of users on their profile pages

JReviews provides 3 JomSocial plugins for user profiles:

MyListings - displays listings submitted by the user

MyReviews - displays reviews submitted by the user

MyFavorites - displays list of user's favorite listings

These plugins are not installed by default. To install them, download the latest JReviews package from the client area and locate these installation files:

/package_jreviews_2.4.x_unzip_first/plugins_jomsocial/jreviews_mylistings.zip

/package_jreviews_2.4.x_unzip_first/plugins_jomsocial/jreviews_myreviews.zip

/package_jreviews_2.4.x_unzip_first/plugins_jomsocial/jreviews_myfavorites.zip

Those plugins need to be installed using Joomla Extension Manager installer:

After the installation, go to the Joomla Plugin Manager and publish the plugins.

Click on the plugins to adjust their parameters. Most of the plugin parameters are the same as those of JReviews Listings and JReviews Reviews modules, but there are 2 additional JomSocial parameters that define how the plugin will display in user profiles:

Core Application - if set to Yes, the plugin will be automatically installed for all users. If set to No, the plugin will be displayed only in profiles of users that installed it themselves via their profile settings.

Position - you can choose to show the plugin in the Main content of the user profile or in the profile sidebar.

Example of a MyReviews plugin displayed in a user profile:

7.1.2.4 Integrating with JomSocial User Points

If you want users to be awarded with points when they submit listings, reviews, comments or media, it is necessary to import JReviews rules for points. They are automatically installed, you only need to go to the JomSocial's User Points page and click the Rule Scan button:

Go to the main User Points page and you should see all JReviews rules:

You can unpublish rules that you don't want to use and adjust the number of points that will be awarded.

7.1.2.5 Integrating JomSocial and JReviews Everywhere add-on for profile reviews

With JReviews Everywhere add-on you can have the ability for users to review each other. This integration is shown in the Everywhere add-on manual.

7.1.3 CommunityBuilder Integration

7.1.3.1 Displaying user avatars in their listings, reviews, comments and linking to their profiles

To show user avatars in their listings, reviews and comments with links to their Community Builder profiles, it is required to enable Community Builder integration in JReviews Configuration:

Example of a user review with avatar and a link to the user profile:

7.1.3.2 Displaying listings, reviews and favorites of users on their profile pages

JReviews provides 3 Community Builder plugins for user profiles:

MyListings - displays listings submitted by the user

MyReviews - displays reviews submitted by the user

MyFavorites - displays list of user's favorite listings

These plugins are not installed by default. To install them, download the latest JReviews package from the client area and locate these installation files:

/package_jreviews_2.4.x_unzip_first/plugins_community_builder/plug_cbjreviewsmylistings.zip

/package_jreviews_2.4.x_unzip_first/plugins_community_builder/plug_cbjreviewsmyreviews.zip

/package_jreviews_2.4.x_unzip_first/plugins_community_builder/plug_cbjreviewsfavorites.zip

To install the plugins, go to the Community Builder component, click the Plugin Management and at the bottom of the page you will find the plugin installer:

Publish the plugins after the installation.

To configure the plugins, go to the Community Builder Tab Management and click on a plugin name. Most of the plugin parameters are the same as those of JReviews Listings and JReviews Reviews modules.

Example of a MyReviews plugin displayed in a user profile:

7.1.3.3 Integrating Community Builder and JReviews Everywhere add-on for profile reviews

With JReviews Everywhere add-on you can have the ability for users to review each other. This integration is shown in the Everywhere add-on manual.

7.2 Setup Facebook Integration

The JReviews integration with Facebook allows you to create incremental traffic to your site, by posting user submitted actions to their Facebook walls. These will also appear in the newsfeeds of the user's friends which creates a viral effect.

7.2.1 Which actions will generate a Wall post?

Currently the actions supported by this integration are submissions of unmoderated listings, reviews and helpful review votes, which are similar to the "like it" functionality of Facebook, but for user reviews in JReviews.

With any of the above actions, the listing or review information will appear in the user's Facebook wall, including a link back to the detail page, the listing image if available, and the user rating where appropriate. This is how a review submission will look like in the reviewer's wall:

Helpful review voting will only generate a wall post if the user has already established a Facebook session; unlike reviews and listings, there's no practical way to ask the user to publish the vote to FB. If users log into your site via Facebook connect, then positive votes will automatically generate a wall post with the review the user liked.

7.2.2 Are there any special requirements

The integration will work with or without a Facebook Connect Joomla login. If your site already supports Facebook Connect login, via JFBConnect, JomSocial, Community Builder or any other solution, then JReviews is able to identify the Facebook session for the current user and use it to submit directly to his Wall. This is transparent to the user.

If the user has not granted publish stream permissions or if the user is not logged in via Facebook, then he will see the following checkbox option above the submit button in both review and listing forms:

When the user clicks on the checkbox or FB button the Facebook Popup will appear requesting login information or publish stream permissions or both. This button will only appear for users not logged in via Facebook or users that haven't granted publish permissions. If you decide you want to allow users to opt-out of publishing the submissions to their Facebook wall, you can enable the opt-out setting in the JReviews configuration for Facebook.

7.2.3 Facebook API Compatibility Notice

JReviews uses only the latest FB javascript and PHP APIs and will not work with websites that use the old API for Facebook Connect functionality. You can find references to the old JavaScript SDK by searching for the string "FeatureLoader.js.php in your page source.

7.2.4 How to setup the Facebook Integration

In the JReviews configuration, under the Community tab you need to enter a Facebook Application ID and Secret strings. If you already have a Facebook application for your site login, then you can use the strings from that application, otherwise you need to go to https://developers.facebook.com/apps and create a new application.

Once you click the Create New App, you'll need to enter the application name and agree to the license terms.

The next step is to configure the application:

Copy the Application ID and Secret values from your new app and paste them in the JReviews Configuration, Community tab:

7.2.5 Troubleshooting

Testing the integration

To test whether the integration is working, make sure you don't have an active Facebook session when using Facebook Connect to log in to your site. Go to the Facebook site and log out. Then go back to your site and navigate to a page where you can see the review form. Click on add review and look for the Publish to Facebook button as shown in the second image from the top. If it's not there, make sure you are accessing the site as a user for which moderation is not enabled because this only works without moderation.

A few steps to go over if it doesn't work

If you have another Facebook Connect extension used for user login, make sure it uses the most recent javascript SDK (API). Instructions for checking this are above

Make sure you used the Facebook Application ID in the configuration instead of the API Key. Components like JomSocial use the API Key; therefore just copying your settings will not work.

Make sure you disabled the moderation for listings and/or reviews for the user group for which you are testing this feature. The FB integration only works with unmoderated submissions.

7.3 Setup Twitter Integration

The JReviews integration with Twitter allows you to create incremental traffic to your site by posting updates to your Twitter account based on user submitted actions.

7.3.1 Which actions will generated a Twitter update?

Currently the actions supported by this integration are submissions of new listings, reviews and review comments.

With any of the above actions there will be a Twitter update to your account linking back to the related page on your site. For moderated submissions the updates will be posted on moderator approval.

7.3.2 How to setup the Twitter Integration

First you need to create a Twitter app. Go to http://developer.twitter.com and log in. Under your username click on "My Applications" link:

On the next page click the Create a new application button:

Then fill in your app details:

On this page you'll need to accept "Developer Rules", fill in captcha and click the Create your Twitter application button at the bottom.

On the next page click on the Settings tab and choose Read & Write for app access:

At the bottom of the page click Update this Twitter's application setting button and then return to the first tab.

On the first tab click Create my access token button and reload the page.

Now you have all required app information that you need to enter in JReviews Configuration settings:

Consumer Key

Consumer Secret

Access Token

Access Token Secret

7.3.3 Integrating bit.ly

For the automatic tweets to include links to the listings on your site, you also need a bit.ly account. Make sure to create a real account instead of using your Twitter account to access bit.ly.

In JReviews Configuration you will need to enter your bit.ly username and API Key. To find the API Key, in your bit.ly account click on the Settings link, go to the Advanced tab and click the Show legacy API key link:

7.3.4 Troubleshooting

If the twitter integration is not working, these are the first things you need to check:

Make sure your Twitter App has Read & Write access.

Make sure you entered the callback url as shown above.

Make sure your server time settings are correct. If the server time settings are different than those of Twitter then the Oauth athentication will result in a 401 error. More details about this problem can be read here https://github.com/abraham/twitteroauth/issues/44.

Chapter 8 Theme Customizations

8.1 How does the JReviews Theme Engine work

JReviews uses a php templating system. This means you can mix html with php code, which provides a lot of flexibility to create conditionals and add snippets of php code.

JReviews themes are located in this folder:

/components/com_jreviews/jreviews/views/themes/

You will find several themes there:

/components/com_jreviews/jreviews/views/themes/default/

/components/com_jreviews/jreviews/views/themes/dark/ - for using with dark joomla templates

/components/com_jreviews/jreviews/views/themes/mobile/ - for mobile devices

You will notice that "dark" and "mobile" theme folders contain less files than the "default" theme folder. The default theme is a "fallback" theme which contains all the necessary files, while dark and mobile themes are variations of the default theme and contain only "modified" files and images. If a theme doesn't contain a certain file, JReviews will load that file from the default theme. That makes updating themes easier.

If you want to make theme customizations, create a custom theme similar to the dark theme. Theme files in the default theme should never be modified.

Instead of creating your custom theme in /components/com_jreviews/jreviews/views/themes/ folder, you should use the JReviews Code Overrides functionality to place your custom theme outside the /com_jreviews folder. That way you won't lose your custom theme when you upgrade JReviews.

You will find 3 settings for theme selection in JReviews Configuration:

Site theme - this is the main theme that will be used for the JReviews frontend. If you will create a custom theme, this is where you'd select it.

Mobile theme - here you can choose a theme that will be used on smartphones. It is recommended to select the same theme that you selected for Site theme. The Default Theme is responsive and works fine on mobile devices by default. The only reason why you might want to use a separate mobile theme is if you want to delete certain page elements only for smartphones. JReviews includes a Mobile Theme that you can use for this purpose.

Fallback theme - all theme files that the selected Site theme doesn't have will be loaded from the fallback theme. The Default Theme should always be selected here (unless JReviews will have two different fallback themes in the future).

8.2 JReviews Code Overrides

JReviews' code override functionality allows you to override any file located in the JReviews application folder at:

/components/com_jreviews/jreviews/

8.2.1 Why use the complete overrides functionality

The most common way to upgrade a component in Joomla is to uninstall it and then re-install it. This means that any code changes you might have made to the core files of the components could be lost if you don't have a back-up; it is also more difficult to keep track of the files that you've customized. With the code override functionality you can place your customized files in a folder outside of the JReviews component to keep all your customizations in one place and safe from upgrade losses. Of course you still need to check for file differences when there's an upgrade, because there might be bug fixes in your modified files, but now you can easily keep track of which files to check.

8.2.1.1 How do I use this capability?

Easy! Just create a new folder in the templates folder of your Joomla installation called "jreviews_overrides". This folder matches the jreviews folder inside com_jreviews so that:

{site_root}/templates/jreviews_overrides/ = /components/com_jreviews/jreviews/

8.2.2 How to create a custom theme

8.2.2.1 Preparing a custom theme folder

create a "jreviews_overrides" folder inside {site_root}/templates/

create your custom theme folder inside the jreviews_overrides folder like this:

{site_root}/templates/jreviews_overrides/views/themes/mytheme

Important: your custom theme must have a unique name, don't name it the same as one of the existing themes and the folder name must be all lowercase.

create a themeInfo.xml file which will contain the information regarding the theme. You can copy the file from the Dark theme and adjust the values. Here is an example of the themeInfo.xml contents:

<?xml version="1.0" encoding="utf-8"?>
<theme>
    <creationDate>Jan 2014</creationDate>
    <author>ClickFWD</author>
    <authorEmail>support@reviewsforjoomla.com</authorEmail>
    <authorUrl>http://www.reviewsforjoomla.com</authorUrl>
    <copyright>Copyright (C) 2010-2014 ClickFWD LLC. All rights reserved.</copyright>
    <license>Proprietary</license>
    <version>2.4</version>
    <description>This is my custom theme</description>
    <settings>
        <name>mytheme</name>
        <title>My Theme</title>
        <addon>0</addon>
        <configuration>1</configuration>
        <fallback>0</fallback>
    </settings>
</theme>

8.2.2.2 Copying the files from the default theme

after you created the theme folder and the themeInfo.xml file, the next step is to copy the theme files that you want to modify from the default theme and make sure you use the same folder structure, for example:

If you want to modify the /themes/default/listings/detail.thtml file, create a copy like this:

{site_root}/templates/jreviews_overrides/views/themes/mytheme/listings/detail.thtml

Important: do not copy all files from /default theme, only small number of files that you want to modify.

JReviews will always look for images in your custom theme, so copy the /theme_images folder with all its images from the default theme folder to your custom theme:

{site_root}/templates/jreviews_overrides/views/themes/mytheme/theme_images

if you will have css files in your custom theme you'll also need to copy the /theme_css/images folder to the custom theme.

you shouldn't copy the core css files into your custom theme, instead copy only custom_styles.css and custom_styles_modules.css files, the styles you add there will override styles of core css files.

use custom_styles.css for styles of JReviews pages, and use custom_styles_modules.css for module styles.

Important: after you are done adding files to your custom theme, for JReviews to recognize new files, you must click the 'Clear Cache & File Registry' link in JReviews Administration:

when you make modifications to the theme files, but the modifications aren't visible on the site, you probably need to clear the browser's cache to see the changes (in some cases it will be necessary to clear cache in JReviews and Joomla also).

8.2.2.3 Using your custom theme

Go to JReviews Configuration, tab 'General' and select your custom theme from the Site Theme and Mobile Theme dropdown:

Note: Fallback Theme dropdown must always be set to Default theme, so that the files that don't exist in your custom theme are loaded from the default theme.

8.2.3 Modifying the theme files of add-ons

JReviews add-ons have their own themes which are located in:

/components/com_jreviews_addons/{add-on_name}/views/themes/{theme_name}

If you want to modify the files that exist in those themes of add-ons, copy those files into your custom JReviews theme the same as if they existed in the default theme folder.

For example, if you want to customize this theme file:

/components/com_jreviews_addons/geomaps/views/themes/geomaps/geomaps/map_detail.thtml

it would go into this folder:

/templates/jreviews_overrides/views/themes/mytheme/geomaps/map_detail.thtml

Some of the add-ons have their own css files as well, but you should never customize those or copy them to your custom theme. Instead, copy specific css styles that you want to customize into the custom_styles.css file in your JReviews theme and adjust the styles there.

8.2.4 Modifying JReviews core files

It is recommended not to make too many modifications to the JReviews core files, in order to make future upgrades easier; but you can do it the same way as when modifying theme files.

For example, if you want to override a controller file (i.e. listings_controller.php), you would copy it here:

/templates/jreviews_overrides/controllers/listings_controllers.php

The framework will always check in the jreviews_overrides folder first to see if the file is there and if found it will use it instead of the core file.

Keep in mind that anytime you add a file to the overrides folder you need to clear the File Registry in the JReviews administration. Doing this allows JReviews to recognize the new file. Otherwise it will continue reading the file from the main component folder.

8.3 What happens with modified files when JReviews is upgraded

When JReviews is re-installed or upgraded, the whole /components/com_jreviews folder is replaced with the new version, which is why it is important to make your modifications inside the /jreviews_overrides folder.

Your modified files in the jreviews_overrides folder will not be deleted when JReviews is upgraded, but you will need to update those modified files if they are changed in new version of JReviews. When a new JReviews version is released, you should first check if some of the files that you customized have been updated in the latest release by comparing them with the list of updated files.

If some of the files that you modified have been updated in the new version of JReviews, you have two options:

update your modified file with changes in new version of the file, or

copy the new version of the file and re-do your modifications

If a file has many changes in the new version, a second option might be better because you are more familiar with your old modifications and re-doing them will be easier than implementing new changes into your modified file.

Comparing files for differences would be difficult without some tools. On windows, you can use Beyond Compare (commercial) or WinMerge (open source). On Mac OS, you can use CompareMerge (commercial) or Kaleidoscope (commercial).

Here is an example of the detail.thtml file comparison between JReviews versions 2.4.9.1 and 2.4.12.4 using CompareMerge:

8.4 Theme debugging tools

In JReviews Configuration you will find debugging tools:

8.4.1 Debug PHP & Queries

This option is very useful during development when something doesn't work because of php or database errors. Enabling it will display all php errors and database queries below all content on pages.

8.4.2 Debug Themes

This option is very useful if you don't know which file or function outputs specific elements of JReviews pages.

If you enable this option, it will show the theme output of each theme labeled with the theme filepath as well as the controller filename and function is used to process the output. Example:

8.4.3 Debug IP

Enter your IP address to the Debug IP input when you enable Debug options so that other visitors of your site won't see debug info.

8.5 How to edit .thtml theme files

JReviews themes use .thtml files which are "php + html" template files. To modify .thtml files, you need a text editor. Any text editor like notepad would work, but it's better to use more powerful code editors with syntax highlighting and other features.

8.5.1 Some of the popular code editors

Notepad++ (Windows) - free

TextWrangler (Mac) - free

jEdit (Windows, Linux, Mac) - free

Sublime Text (Windows, Linux, Mac) - commercial

Most of the code editors will display .thtml files as regular text, without syntax highlighting by default, but in each of them you can enable PHP highlighting for .thtml files.

8.6 How to edit the JReviews language files

JReviews uses language files for all the text that is used in the themes. To change the text or translate it to a different language you need to edit the files in:

/components/com_jreviews/jreviews/locale/

There's a folder for each language. You can modify the default.po file for your language or copy one of the 3-letter word language folders and rename it for your language. Then edit the default.po file.

When translating or changing the .po file it is very important to keep the character encoding of the file. In order to do this you need to use a special editor like Notepad++ or Poedit. Both are free applications. The files must be saved with UTF-8 encoding.

When changing the file it is only necessary to change the msgstr, changing the msgid will not work. For example:

#: jreviews\views/helpers/custom_fields.php:312
#: jreviews\views/helpers/custom_fields.php:462
msgid "Submit"
msgstr "Submit"

would be changed like this for a Spanish translation:

#: jreviews\views/helpers/custom_fields.php:312
#: jreviews\views/helpers/custom_fields.php:462
msgid "Submit"
msgstr "Enviar"

The msgid serves as the lookup reference from the .thtml theme files, where you'll find it in this format:

__t("Submit");

There is no need to change the theme .thtml files for translation, but if you do change the references in the __t("text"); format, then those will not be translatable via the language file unless you add to them new reference:

msgid "text"
msgstr "translated text"

After making changes to a language file you must clear the cache in JReviews using the "Clear Cache & File Registry" link in the JReviews administration:

You need to do this even if caching is disabled in JReviews.

It is recommended to use the JReviews Code Overrides functionality to make modifications to language files outside the /com_jreviews folder so that your changes are not lost after you upgrade JReviews.

For example, if you want to customize the spanish language, copy the spanish language folder:

/components/com_jreviews/jreviews/locale/spa/

into the jreviews_overrides folder like this:

/templates/jreviews_overrides/locale/spa/

8.7 Tools for customizing JReviews Themes

If you use the Chrome browser, the best tools are the default DevTools:

You can right-click on any element on the page and click Inspect Element. That will open up the Element tab of the Chrome DevTools and you will be able to inspect the html code and see all css styles that are applied to that specific element.

Check the Chrome DevTools Guide for more info on how to use it.

If you use Firefox, there are default development tools available as well, but you can also use a powerful add-on called Firebug.

8.8 Default theme overview

The default JReviews theme is located in this folder:

\components\com_jreviews\jreviews\views\themes\default

This is the structure of the theme:

/claims - listing claims submission form.

/community_plugins - theme files of plugins used with EasySocial, JomSocial and Community Builder.

/directories

/directory.thtml - "Yahoo style" directory page.

/discussions - theme files for user review discussions.

/elements - various theme files that are included in other theme files.

/email_templates - templates for e-mail notifications.

/everywhere - user reviews theme file for Everywhere Add-on.

/feeds - theme files for RSS feeds.

/inquiries - inquiry form theme file.

/listings

/create.thtml - submit listing page.

/create_form.thtml - submit listing form.

/create_form_tabbed.thtml - alternative theme file of the submit listing form that uses tabs for fields.

/detail.thtml - theme file of the listing detail page.

/detail_tabs.thtml - alternative theme file of the listing detail page that uses tabs.

/detail_compact.thtml - alternative "compact" theme file of the listing detail page.

/listings_blogview.thtml - blogview list page layout.

/listings_blogview_compact.thtml - "compact" blogview list page layout.

/listings_compare.thtml - listing comparison page.

/listings_header.thtml - header of list pages, used on top of blogview, tableview, thumbview and masonry layouts.

/listings_masonry.thtml - masonry list page layout.

/listings_tableview.thtml - tableview list page layout.

/listings_thumbview.thtml - thumbview list page layout.

/media - theme files for all media elements in JReviews (photos, videos, attachments, audio).

/modules - theme files of all JReviews modules.

/owner_reply - submit form for owner replies in reviews

/reports - review report submit form

/reviews

/create.thtml - submit review form.

/editor_reviews.thtml - editor reviews layout.

/review_layout.thtml - layout of individual reviews on listing detail pages.

/review_list_layout.thtml - layout of individual reviews on list pages.

/user_reviews.thtml.thtml - user reviews layout.

/search - advanced search page

/sitemaps - video sitemap theme file

/theme_css - all css files and images used by css files

/theme_images - all theme images

/theme_layouts - containers of other theme files, no need to modify

themeInfo.xml - the required file that contains info about the theme.

8.9 Variables you can use in theme files

8.9.1 $listing array

The $listing array contains all the data of a certain listing.

It is used in these files:

/listings/detail.thtml

/listings/detail_tabs.thtml

/listings/detail_compact.thtml

/listings/listings_blogview.thtml

/listings/listings_blogview_compact.thtml

/listings/listings_tableview.thtml

/listings/listings_thumbview.thtml

/listings/listings_masonry.thtml

/modules/listings.thtml

In those files you can add any data from the $listing array. Here is a list of mostly used ones:

Listing ID

<?php echo $listing['Listing']['listing_id'];?>

Listing Title

<?php echo $listing['Listing']['title'];?>

Listing Alias

<?php echo $listing['Listing']['slug'];?>

Listing summary text

<?php echo $listing['Listing']['summary'];?>

Listing description text

<?php echo $listing['Listing']['description'];?>

Summary + Description

<?php echo $listing['Listing']['text'];?>

Media count

<?php echo $listing['Listing']['media_count'];?>

Photo count

<?php echo $listing['Listing']['photo_count'];?>

Video count

<?php echo $listing['Listing']['video_count'];?>

Audio count

<?php echo $listing['Listing']['audio_count'];?>

Attachment count

<?php echo $listing['Listing']['attachment_count'];?>

Number of visits

<?php echo $listing['Listing']['hits'];?>

Created date

<?php echo $Time->nice($listing['Listing']['created']);?>

Modified date

<?php echo $Time->nice($listing['Listing']['modified']);?>

Category ID

<?php echo $listing['Category']['cat_id'];?>

Category Title

<?php echo $listing['Category']['title'];?>

Directory ID

<?php echo $listing['Directory']['dir_id'];?>

Directory Title

<?php echo $listing['Directory']['title'];?>

Listing Type ID

<?php echo $listing['Criteria']['criteria_id'];?>

Listing Type Title

<?php echo $listing['Criteria']['title'];?>

Listing author's ID

<?php echo $listing['User']['user_id'];?>

Listing author's real name

<?php echo $listing['User']['name'];?>

Listing author's username

<?php echo $listing['User']['username'];?>

Listing author's email

<?php echo $listing['User']['email'];?>

User rating

<?php echo $listing['Review']['user_rating'];?

Number of user ratings

<?php echo $listing['Review']['user_rating_count'];?>

Number of user reviews

<?php echo $listing['Review']['review_count'];?>

Editor rating

<?php echo $listing['Review']['editor_rating'];?>

Number of editor ratings

<?php echo $listing['Review']['editor_rating_count'];?>

Number of editor reviews

<?php echo $listing['Review']['editor_review_count'];?>

Number of users who added listing to their favorite list

<?php echo $listing['Favorite']['favored'];?>

8.9.2 Conditionals

You can use any of the above variables to create conditionals, for example:

<?php if($listing['Review']['review_count']): // if user review exists ?>
  // display something
<?php else: ?>
  // display something else
<?php endif;?>

8.9.3 How to customize the layout of custom fields in theme files

To simplify the initial setup of JReviews, there's a default output of custom fields for both listings and reviews. If you want to customize them, you can unpublish the fields from both list and detail views in the Fields Manager, and place the fields where you want them in the theme files.

Besides using custom code for custom fields in the theme files, it is possible to customize the field output using the Banner field type.

Custom field placement also allows to use fields in javascript code for Google Maps and other scripts you may want to use.

The following code works in these files:

/listings/detail.thtml
/listings/detail_compact.thtml
/listings/detail_tabs.thtml
/listings/listings_blogview.thtml
/listings/listings_blogview_compact.thtml
/listings/listings_tableview.thtml
/listings/listings_thumbview.thtml
/listings/listings_masonry.thtml
/modules/listings.thtml
/modules/listings_slideshow.thtml
/modules/listings_vertical.thtml

8.9.3.1 Outputting a certain listing custom field

In all code examples below replace jr_fieldname with the name of the field that you want to output.

Outputs the field label

This code will output the label of the field where you place the code in the theme file:

<?php echo $CustomFields->label('jr_fieldname',$listing); ?>

Outputs the field value text

This code will output the text of the field value where you place the code in the theme file:

<?php echo $CustomFields->field('jr_fieldname',$listing); ?>

Outputs the field value

If you have a custom field with field options, this code will output the value of the field as it is referenced in the database:

<?php echo $CustomFields->fieldValue('jr_fieldname',$listing); ?>

Get field text without click2search or output re-format

You can also have a bit more control of the output by using additional parameters when you call the display method: $CustomFields->field($name, &$element, $click2search = true, $outputReformat = true)

The example below calls the brand field and turns off click2search and outputreformat advanced options:

<?php echo $CustomFields->field('jr_fieldname',$listing,false,false); ?>

Get text of selected option for select list with images

If you have a select field with images associated to options and want to get the field text for the selected option, use this code:

<?php echo $CustomFields->fieldText('jr_fieldname',$listing,false,false); ?>

8.9.3.2 Outputting a certain field group

Outputs a whole field group using the default output:

<?php echo $CustomFields->displayAll($listing,'content','group-name');?>

Replace group-name with the name of the field group that you want to output. You can use this to put different groups in different tabs when combined with a tabs plugin.

Outputs multiple field groups:

<?php echo $CustomFields->displayAll($listing,'content', array('includeGroups' => array('group-name1', 'group-name2')));?>

Outputs all field groups except specified:

<?php echo $CustomFields->displayAll($listing,'content', array('excludeGroups' => array('group-name1', 'group-name2')));?>

8.9.3.3 Review custom fields

You can place review custom fields in these files:

/reviews/review_layout.thtml
/reviews/review_list_layout.thtml
/modules/reviews.thtml

Outputs the field label

This code will output the label of the field where you place the code in the theme file:

<?php echo $CustomFields->label('jr_fieldname',$review); ?>

Outputs the field value text

This code will output the text of the field value where you place the code in the theme file:

<?php echo $CustomFields->field('jr_fieldname',$review); ?>

8.9.3.4 Custom field conditionals

If you want to output certain code only if the specific custom field isn't empty, you can use this code:

<?php if($CustomFields->field('jr_fieldname',$listing,false,false) != ''):?>
  <!-- Add your code here-->
<?php endif;?>

If you want to output certain code only if the specific custom field has a specific value, you can use this code:

<?php if($CustomFields->field('jr_fieldname',$listing,false,false) == 'some-value'):?>
  <!-- Add your code here-->
<?php endif;?>

If you have a multiple select or checkbox type of custom field and you want to check if it has a specific value, use this code:

<?php if (in_array('some-value', $CustomFields->fieldValue('jr_fieldname',$listing))): ?>
  <!-- Add your code here-->
<?php endif; ?>

8.10 Customizing the listing detail page

The listing detail page contains all information about a specific listing (custom fields, media items, reviews, etc.). Here is an example of a listing detail page on the demo site.

If you want to customize the layout of the listing detail page, this is where its default theme file is located:

/com_jreviews/jreviews/views/themes/default/listings/detail.thtml

Before making any theme changes, read about JReviews Code Overrides and create a custom theme.

Almost every block of code in detail.thtml is commented to make it easier to find what you want to modify.

You can make any modifications below the "EDIT HTML BELOW THIS LINE" comment.

The detail.thtml theme file also includes some other theme files. For example, this line:

<?php echo $this->element('listing_detail_media',array('position'=>'top','mainMedia'=>$mainMedia));?>

loads a separate theme file which includes all code for listing media items:

/com_jreviews/jreviews/views/themes/default/elements/listing_detail_media.thtml

This code:

<?php echo $this->renderControllerView('reviews','user_reviews',array('listing'=>$listing))?>

loads a separate theme file which includes all code for user reviews:

/com_jreviews/jreviews/views/themes/default/reviews/user_reviews.thtml

Most of the listing data is stored in the $listing array. To see the contents of this array, add this line to the detail.thtml:

prx($listing);

8.11 Customizing the list page

List pages display a list of listings. Those are category pages, search result pages and any other special type of pages which displays multiple listings.

Here is an example of a category list page on the demo site.

There are 4 different layouts available for list pages: Blogview, Tableview, Thumbview and Masonry. Each of those have their own theme files:

/com_jreviews/jreviews/views/themes/default/listings/listings_blogview.thtml - Blogview
/com_jreviews/jreviews/views/themes/default/listings/listings_tableview.thtml - Tableview
/com_jreviews/jreviews/views/themes/default/listings/listings_thumbview.thtml - Thumbview
/com_jreviews/jreviews/views/themes/default/listings/listings_masonry.thtml - Masonry

Before making any theme changes, read about JReviews Code Overrides and create a custom theme.

Every list page also includes a separate "list page header" theme file which contains the pagination, page title, category list, etc. This is the theme file:

/com_jreviews/jreviews/views/themes/default/listings/listings_header.thtml

Chapter 9 FAQs

9.1 Troubleshooting FAQ

For any type of problem, if you have recently modified any core php JReviews files, you must revert to the original to make sure the issue is unrelated to your changes.

9.1.1 License

Why do I see a license expiration in the JReviews admin if I purchased a never expiring license

Even though your license never expires, the local key has a valid life of 15 days. When the 15-day period has passed, the key is automatically renewed and stored in the database. This is done to reduce the risk of fraud. It also provides a way to let you move the license to a different domain if required. For further information on how the license works read [How does the JReviews license work][].

9.1.2 Client Area

I can't find the downloads for GeoMaps, PaidListings, WidgetFactory or Everywhere add-ons

The add-ons don't have client area downloads. The Everywhere add-on is bundled with JReviews and will show up in the admin screen once you submit your license number. GeoMaps, PaidListings and WidgetFactory add-ons are installed via the remote installer/updater menu in the JReviews administration:

Just purchased an add-on but it says it’s not active

Go to the JReviews admin license screen. Clear the local key text area and re-submit the license number. This will fetch a new local key that includes the recently purchased add-on information. If that doesn't work submit a ticket.

9.1.3 Installation & Configuration

I am getting an ionCube not installed error

Site error: the file /some/path/components/com_jreviews/jreviews/admin_controllers/my_controller.php requires the ionCube PHP Loader ioncube_loader_lin_5.3.so to be installed by the site administrator.

If this is the first time you install JReviews, you must also install the ionCube loaders on your site. Read the JReviews Pre-install requirements.

If it was working before, this means something changed on your server that made the ionCube loaders stop working. You will need to contact your host to find out what they changed. You might need to upgrade the loaders to the latest version.

I cannot install JReviews, get the error "There was an error uploading this file to the server. Unable to find install package."

Some servers don't allow uploading files larger than 2 MB by default. To check if this is the case on your server, go to the System Information page in Joomla Administration, click the PHP Information tab and search for upload_max_filesize setting:

This value should be set to at least 8M. If it is lower, you will need to edit the php.ini file on your server, find the upload_max_filesize setting and increase its value.

You also need to make sure you are uploading the correct installation file. Read Installing JReviews component for more info.

9.1.4 Media

I get "Upload directory is not writable" error when uploading media

This issue is typically caused by a wrong configuration for the 'tmp' folder in the Joomla configuration.php file. This folder is used to temporarily store the uploaded media for further processing.

This can happen if you moved your site to a different folder or a different host. Whenever you do that, you need to edit the configuration.php file and update the path to the tmp folder.

9.1.5 Menus, SEF and Modules

Module assignments are lost on detail pages

For proper module assignments to listing detail pages, you need to create the Required Joomla Menu Items.

Custom title set in SEO Manager not working

If you configured a custom listing title in the Listing Type SEO Manager, it will not work by default because of a bug in Joomla 2.5 and 3.x.

To fix the bug, you will need to replace this file:

components/com_content/views/article/view.html.php

with the patched file that can be downloaded here:

For Joomla 2.5.x: view.html.php_2.5.zip

For Joomla 3.1.x: view.html.php_3.1.zip

For Joomla 3.2.x: view.html.php_3.2.zip

Why are some of my JReviews pages showing homepage modules

When certain page doesn't have an ItemID in url, Joomla will show on that page only those modules that are set to display on all pages.

But some Joomla templates (mostly RocketTheme templates) have a feature to instead show all homepage modules on pages without ItemID and that feature is enabled by default.

To disable it in RocketTheme templates, go to template parameters, click on Advanced and at the bottom you will find this setting:

You can turn it off or change the menu whose modules you want to show on pages without an ItemID.

If you have this issue for listing detail pages also, it means they don't have any ItemID which is not good. To fix that, you should create the Required Joomla Menu Items.

How to fix broken layout of Listings and Reviews modules

JReviews Listings Module and Reviews Module use a jQuery plugin for module pagination and slideshow functionality.

This plugin requires that the module has fixed dimensions and it tries to automatically calculate the available dimensions within the parent element. In some cases this is not possible. For example, if you output the module inside a tab that is hidden by default, the module will not be able to calculate the available dimensions. To fix that, you can try to set fixed dimensions to the module's parent element. If that won't help, the only options are to publish the module to a different position where the dimensions can be calculated or to disable the pagination/slideshow. To disable the pagination/slideshow, you just need to set the Max. number of results and Results per page module parameters to have the same number.

9.1.6 Errors and things that don't work

Creating new custom fields no longer works

If you have a lot of custom fields in the Fields Manager and creating new custom fields stopped working, the reason is that you reached the database limit for those types of custom fields. To increase the possible number of custom fields, it is necessary to set an optimal number of Maximum Characters for existing fields in the Fields Manager.

Most field types in JReviews use varchar for the column datatype in the database which makes it possible to add indexes and improve performance.

By default, when you create a custom field, JReviews will assign it maximum 255 characters. Most likely some of your custom fields don't need that many characters and reducing this number for those existing fields will open up space for new custom fields.

To adjust the number of maximum characters, go to the Fields Manager, click on one of the field names, locate the Maximum Characters setting and click the button to adjust the number of maximum characters, for example:

In this example for the City custom field, JReviews tells us that currently the longest existing city value has 15 characters, but we set the "Maximum Characters" setting to 30, just in case longer values will be necessary later.

If the setting was set to 255 by default and you reduced it to 30, that will open up space for several new fields.

Multiple select and Checkboxes field types will require more characters because each listing can store multiple field values.

Ordering and/or pagination links are not working

If you have installed sh404sef, make sure you also enabled Joomla SEF as explained here: Using sh404SEF with JReviews.

If JReviews category page urls are not sef, then sh404sef is not setup correctly.

The listing or review form submission hangs

Add the &tmpl=component param to the url. If you use a sef component then add ?tmpl=component. This will remove your Joomla template and modules and load JReviews by itself. Now try the submission again. If it works it means there’s a conflict with a module or plugin that is also loading on that page.

Look at the source of the page (without the tmpl=component parameter) on your browser and search for other instances of jQuery. If another extension loads jQuery you need to disable it to find out if that is what is causing the problem.

Try disabling 3rd party plugins and modules until you find the conflicting one.

Check the conflicts board on the forum.

Try disabling email notifications and auto-tweets in order to rule those out as being the cause of the problem.

Use Firebug to view the response of the ajax request once you click on submit. This will appear in the Console tab in Firebug and you need to click on the response tab of the request that appears when you press the submit button. Let us know what the response is in your forum post or ticket.

9.2 License FAQ

9.2.1 How does the JReviews license work

Why use a licensing system?

You are allowed to install JReviews on a single domain per license. To enforce this we use a licensing system based on local key and remote checking. We think this system provides the most flexibility because:

(a) it allows you to move your license to a different domain if you need to; and

(b) if you don't like the remote checking you can request a permanent key in the Client Area two months after placing your order. After requesting a permanent key, you won't be able to move your license to a different domain.

Why does JReviews require me to manually copy the local key every two weeks?

The update of the local key should take place automatically and be transparent to you. However, if your server has a firewall it's possible that it is blocking communication to remote servers and prevents JReviews from verifying the license. To get around this you need to open up the host for JReviews (ping reviewsforjoomla.com) or make your local key permanent.

Why does it say the local key expires in the JReviews administration?

Even though your license never expires, the local key has a valid life of 15 days. When the 15-day period has passed, the key is automatically renewed and stored in the database. This is done to reduce the risk of fraud and enables you to move the license as explained above in point a).

Can I disable the periodic verification of the license?

Yes, as stated above two months after purchasing a license you can make your local key permanent and disable the remote license check. You can do this in the Client Area under your license details. There you'll find a button to make the key permanent. The button will appear only if the license is active and if you haven't already made the key permanent.

Can I use the license in subdomains?

You are allowed to use JReviews in subdomains. This excludes domain suffixes, such as countries and business types. For example .com, .org and .net are different domains. To enable the license to work on subdomains please submit a ticket, after activation, requesting the license change.

9.2.2 Can I remove the "Powered by" link

Yes, you can remove it. However, it would be great if you can promote JReviews to everyone you know or provide credit in some other way to help us with the traffic to our site so we can continue providing excellent support and upgrades.

You will need to edit the file: * /components/com_jreviews/jreviews/views/themes/default/elements/credit.thtml

And remove the following code:

<div style="margin:20px 0 20px 0;text-align:right;font-size:85%;">
    Powered by <a rel="nofollow" href="http://www.reviewsforjoomla.com/" title="Joomla CCK and Reviews">JReviews</a>
</div>

Do not change the text to Powered by XYZ, it goes against the license terms.

You can make this change once and not worry about it on upgrades by using the JReviews Code Overrides feature.

9.2.3 Can I install JReviews in a development domain

Yes, you can install JReviews in both production and development domains. JReviews also works by default on http://localhost. To request the addition of a development domain to your license or if you are having trouble using the license on localhost, please submit a ticket. Development domains need to be a real domain and not an ip address.

9.2.4 Can I move the JReviews license to a different domain

Yes, to move the license you will need to reissue it. To do this, first log in on our website and then go to the Client Area.

If you can't access the client area after log-in and instead you see a message saying you are already logged in you can try using a different browser or use this alternate link to log in.

In the Client Area click the View Your Licenses link on the left menu and then click the View & Download button:

On the next page you will find the Reissue License button:

After you click the Reissue License button, the license will no longer be locked to any domain. Then go to the administration area of your new site and submit the license on the JReviews License page.

Note: You do not need to reissue your license to switch between your live domain and development domain. If you have a separate development domain, submit a support ticket to request that we add it to your license, then you will be able to use the same license on both live and development domains.

9.2.5 Can I use one license in domains with different domain suffixes (TLDs)

No, domains with different suffixes, or top level domains, like location and business types (.com,.org,.net) or country specific domains (.de, .uk,.nl,.es) are in fact different domains and you need to purchase a license for each one if you plan on installing different instances of JReviews on them.

If you are using the domains as aliases for the main site and you are using a single Joomla and JReviews installation then you can use a single license on the main site and always access the JReviews administration from the main site.

9.2.6 Can I customize the code to extend the functionality of JReviews

Yes, you can customize both the theme files and the php code. Some of the administration files are encoded, but this doesn't prevent extending the functionality of JReviews.

9.2.7 Is JReviews encoded

Yes, JReviews is partially encoded to protect the license code. The encoding is limited to several administration only files to guarantee that neither encoding, nor licensing issues will ever affect the front-end functionality of the site.

9.3 Client Area FAQ

9.3.1 Where can I download the latest version

To access your license downloads, log in on our website and then go to the Client Area.

If you can't access the client area after log-in and instead you see a message saying you are already logged in you can try using a different browser or use this alternate link to log in.

In the Client Area click the View Your Licenses link on the left menu and then click the View & Download button:

On the next page you will see your license details and available downloads:

You will be able to download the latest version as long as you have a valid upgrades package. You get 12 months of free upgrades. After expiration you need to renew the upgrades if you want to download the most recent version.

Downloading JReviews Add-ons

There is no download link for JReviews Add-ons, they can be installed only directly from JReviews administration!

9.3.2 How do I purchase add-ons and upgrade packages if I already purchased JReviews

Add-ons

For the GeoMaps, PaidListings and WidgetFactory add-ons you must be using the latest version of JReviews in order to be able to install the add-ons. The reason for this is that we are constantly improvement them and fixing reported bugs and are not able to provide support for old versions.

Upgrades & Support

The option to extend your Upgrades & Support Package will only be available for orders that have expired upgrades. If you still have a few days left before your upgrades expiration you will need to wait until the upgrades expire before you can renew them.

To purchase add-ons or extend the JReviews upgrades for 12 months, log in on our website and then go to the Client Area.

If you can't access the client area after log-in and instead you see a message saying you are already logged in you can try using a different browser or use this alternate link to log in.

Click the [http://www.reviewsforjoomla.com/orders/client_orders.php View Your Orders] link to see your orders and click the View button next to the order for which you want to purchase an add-on or extend the upgrades: