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:

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

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:

  1. Listing Field Groups - for listing submit forms
  2. 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:

Other Examples of listing field groups:

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:

3.2.2 Steps to create Field Groups

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:

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:

Decimal number

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

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:

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:

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:

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:

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:

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

Rating Criteria

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

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):

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.