JReviews:Add-on Development

Add-on development requires a basic understanding of PHP and MySQL and JReviews version 2.4.13.1 or higher.

What is an Add-on?

JReviews add-ons can extend the core functionality without the need to modify code in the JReviews core. Add-ons can have administration settings and management functionality, similar to the ones found in GeoMaps, PaidListings and the WidgetFactory. They can have their own front-end menus to create new pages on your site. They can intercept database query requests and modify or extend the results of queries and they can also modify any variable that is sent to a view before the view is rendered.

Creating an Add-on

Add-ons live in the /components/com_jreviews_addons folder and at a minimum must have an XML file and a JReviews plugin PHP file. The XML file lets JReviews identify the add-on. The JReviews plugin PHP file can run code on specific events to modify the front-end functionality. To get started we'll use a simple example that will append the category title to the listing title in detail pages.

Creating the Add-on XML file

The XML filename should match the <name> tag inside the XML file and should also match the add-on's folder name in /components/com_jreviews_addons.

<?xml version="1.0" encoding="utf-8"?>
<addon>   
   <title>Title Modifier</title>
   <name>titlemodifier</name>
   <description><![CDATA[Title Modifier]]></description>
   <author>ClickFWD LLC</author>
   <url>http://www.reviewsforjoomla.com</url>
   <created>02/17/2014</created>
   <version>1.0.0.1</version>
   <copyright>Copyright (C) 2010-2014 ClickFWD LLC</copyright>    
   <license>http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL</license> 
</addon>

Create the folder and file /components/com_jreviews_addons/titlemodifier/titlemodifier.xml. Paste the code above and save. Then go to the JReviews Add-on Manager's Discover tab and you should find the new 'Title Modifier' add-on. Check the box for it and install it.

Now if you switch to the Add-on Manager's 'Manage' tab you'll find your new add-on there:

Creating the Add-on plugin PHP file

The plugin php file is where all of the magic happens for add-ons that want to modify existing functionality. The plugin file can have any name you want, but we typically use the same add-on name for the plugin filename. Create the file /components/com_jreviews_addons/titlemodifier/plugins/titlemodifier.php with the code below:

<?php 
defined( 'MVC_FRAMEWORK') or die;
/**  
* The class name matches the filename with the first letter capitalized  
*/ 
 
class TitlemodifierComponent extends S2Component { 
 
    var $published = false; 
 
    function startup(&$controller) 
    { 
        // We only want the plugin to run in the detail page 
 
        if($controller->name == 'com_content' && $controller->action == 'com_content_view') 
        { 
            // Make the controller properties available in other methods inside this class 
 
            $this->c = &$controller; 
 
            $this->published = true; 
        } 
    } 
 
    /**
     * Event triggered before the theme is rendered
     * All variables sent to theme are available via $this->c->viewVars array
     */ 
 
    function plgBeforeRender() 
    { 
        $listing = & $this->c->viewVars['listing']; 
 
        $listing['Listing']['title'] .= ' - ' . $listing['Category']['title']; 
    } 
}

Next clear the File Registry in the JReviews administration so it can recognize the new file. Go to a listing detail page and voilà. Congratulations! You've built your first add-on. You can disable the add-on by un-publishing it in the 'Add-on Manager'.

Limiting the scope of the add-on to specific pages or actions

It is important to make sure that your add-on code only runs in the pages or actions you want to modify. In the php code above you can find these lines:

        // We only want the plugin to run in the detail page 
 
        if($controller->name == 'com_content' && $controller->action == 'com_content_view')

Every request to a JReviews page or action, like a listing or review submission, goes through a controller and a controller action. The controller is a PHP class and the action is a method or function within that PHP class. All controllers in JReviews and add-ons can be found inside the /controllers folder. When the JReviews detail page is called via the browser URL a request is made to com_content_controller.php, and the 'com_content_view' action (or method) inside that file.

JReviews makes it very easy for you to find out which controller and action are being called through the 'Theme Debug' setting that can be found in the Configuration, General tab. Once you enable this setting, go to a listing detail page and you'll see the name of the controller file and the action (function name) to which the request is being made.

Add-on plugin Events

Events are triggered at different points during the execution of a request. The following are the events that you can use inside the add-on php plugin file.

• plgBeforeDelete: triggered before the Model::delete method
• plgAfterDelete: triggered after the Model::delete method
• plgBeforeRender: triggered before the theme is rendered
• plgAfterFind: triggered after a Model query is run and before the Model AfterFind event
• plgAfterAfterFind: triggered after a Model query is run and after the Model AfterFind event
• plgBeforeSave: triggered before the Model data is stored to the database
• plgAfterSave: triggered after the Model data is stored to the database

These event triggers allow you to execute code at those specific events. They allow you to modify queries before they are run and the results of the queries after they are retrieved. They also allow you to override certain configuration settings and modify variables and arrays before they are sent to the view where theme files are rendered.

Creating administration menus & pages

Add-on administration pages can be used to display configuration settings and manage other add-on tasks. An administration page requires at a minimum an administration controller and a view theme file. To create an administration page for our 'Title Modifier' add-on let's create the following folders and files:

/components/com_jreviews_addons/titlemodifier/views/admin/themes/default/titlemodifier/menu.thtml

/components/com_jreviews_addons/titlemodifier/views/admin/themes/default/titlemodifier/index.thtml

/components/com_jreviews_addons/titlemodifier/admin_controllers/admin_titlemodifier_controller.php

<?php 
defined( 'MVC_FRAMEWORK') or die; 
 
/**
  * The class name matches the file name with the first letter capitalized
  */ 
class TitlemodifierController extends MyController 
{ 
   var $helpers = array('admin/admin_settings'); 
 
   var $components = array('config'); 
 
   function beforeFilter()
   {
      parent::beforeFilter();
   } 
 
   function index()
   {
      return $this->render('titlemodifier','index');
   }
}

Downloadable examples

Date-To-Age Add-on

Downoad Link

The add-on allows you to dynamically calculate and store the age of a person from his birthdate so site visitors can perform searches using the age.

Events used

• plgBeforeSave: The add-on intercepts the submitted form data to retrieve the date from the birthdate custom field. Calculate the age and then add inject the calculated value to the form data so it will be stored with the rest of the fields.

Administration The add-on has an administration page so it can be configured. You can enter the name of date listing and review custom fields as well as the name of the target listing and review field where the age will be stored. If you just want it to work for listings then you only fill out the values for listings and vice-versa. You can also use it for both listings and reviews.

It also has a second placeholder admin page for illustration purposes and without functionality.

Front-end menus The add-on has two different menu types for illustration purposes and without functionality. You can create the add-on menus via the Joomla menu manager where you'll find them under 'JReviews'. Each menu makes a request to a different controller and action and renders a different view (theme file).

Localization The add-on has an english translation where the different language strings can be found. Other locale folders can be created to translate it into more languages.