Custom Theme

The first step towards creating your first theme customization is to create a custom theme using overrides.

Theme Structure & Paths

The first thing to do when getting started with theme customizations is to get familiarized the theme folder structure and the location of the source template files.

The default theme folder can be found at:

Joomla

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

WordPress

wp-content/plugins/jreviews/jreviews/views/themes/default/

And the theme's structure looks like this (not all folders are shown):

`-- default/
    |-- claims/
    |-- elements/
    |-- community_plugins/
    |-- directories/
    |-- discussions/
    |-- .../
    |-- listings/
    |-- reviews/
    |-- theme_css/
    `-- theme_layouts/

If an Add-on has any theme files, then you can find a similar theme folder structure inside each Add-on's views/themes/.

For the most part, the structure is self-explanatory, but there's a handful that are worth mentioning individually:

/elements

Contains smaller, sometimes re-usable, templates extracted from the main template file to make it easier to mantain and customize.

/theme_css

Here you find all CSS files used by the theme. When you override CSS, never copy these files directly into overrides, because overrides are meant to be incremental.

/theme_layouts

Layouts wrap the template output, allowing you to create more complex page layouts. For example, layouts can be used for email templating, by customizing the layout that wraps the email body. They could also be used to create two colum layouts in listing detail pages.

Creating a Custom Theme

A custom theme is necessary to:

Override CSS styles, and you prefer to keep the changes within JReviews, rather than your site's template.
Override theme templates and extend functionality within a given template.

Custom themes are created in the JReviews overrides folder and require an XML file to define some basic information. To begin, create the themeInfo.xml within the directory structure shown below. For the sake of this example, the new custom theme is named mysite.

The recommended way to create this structure and to manage all customizations, is to connect to your server using an FTP client.

Joomla

administrator/
components/
.../
templates/
`-- jreviews_overrides/
	`-- views/
		`-- themes/
			`-- mysite/
				`-- themeInfo.xml

WordPress

In WordPress create the folder in the root of the site

wp-admin/
wp-content/
.../
jreviews_overrides/
`-- views/
    `-- themes/
        `-- mysite/
            `-- themeInfo.xml

Copy the code below to the themeInfo.xml file, and adjust it accordingly.

<?xml version="1.0" encoding="utf-8"?>
<theme>
    <creationDate>July 2020</creationDate>
    <author>Amazing Creations</author>
    <authorEmail>[email protected]</authorEmail>
    <authorUrl>https://www.site.com</authorUrl>
    <copyright>Copyright (C) 2010-200 Amazing Creations</copyright>
    <license>GPL</license>
    <version>1.0</version>
    <description>Amazing Creations Theme</description>
    <settings>
        <name>mysite</name>
        <title>My Site</title>
        <addon>0</addon>
        <configuration>1</configuration>
        <fallback>0</fallback>
    </settings>
</theme>

A couple of important points in the above XML:

name: needs to match the name of the folder used for the theme, which in this case is mytheme.
configuration: needs to be set to 1 for the theme to appear as an option in the configuration.
fallback: need sto be 0, unless you are creating an entire theme from scratch.

Clear Cache & File Registry

Clear the registry in the JReviews admin CP after creating new files in overrides.

Now to Configuration → Theme & Navigation and select the new My Site theme as the Site Theme.

Since so far this is an empty custom theme, everything will continue working like before. The default theme is used as the fallback for all template and CSS files.

Recommended Tools

If you are going to be making CSS and template changes, of course you need to have a basic understanding of CSS, HTML and perhaps a bit of PHP.

Some of these things you can pick up pretty quickly just by looking at some of the examples and the existing files.

There are great tools to make the job easier.

Code editor: Visual Studio Code
FTP Client: Filezilla
Browser: Google Chrome
- Learn about Chrome's Developer Tools
- Get Started With Viewing And Changing CSS
- Install a Chrome extension like Live Editor for CSS so you can test your class overrides directly in the browser

Coming up next:

Dealing With Customizations After Updates

To find out what you need to know about dealing with customizations after updates, read There's an update - Now what?.