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:

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

8.2.2.2 Copying the files from the default theme

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:

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.

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:

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:

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