Getting Started
The related listings detail page widgets functionality is quite extensive, but if you need something simpler, you can explore an earlier method for embedding related listings through template customizations.
The related listings in these examples all share a common custom field and the code should be included in the listings/detail.thtml template in your custom theme.
The simplest implementation looks like this:
<?php
echo $this->element('related_listings',[
'field' => 'jr_fieldname'
]);
?>
And that will show other listings where the value set for the jr_fieldname field matches the value of the current listing.
Listings in the Same City
For restaurant listings, you can use jr_city to show other listings in the same city and we can also use the city's text in a heading.
<h2>More Places in <?php echo $CustomFields->field('jr_city',$listing,false,false); ?></h2>
<?php
echo $this->element('related_listings',[
'field' => 'jr_city',
'listing_order' => 'rating',
'themelayout' => 'vertical',
'orientation' => 'native-scroll'
]);
?>
You can see that in addition to the field option, there's a few other options there for listing_order, themelayout and orientation. All of these are optional, but they provide more control over the data retrieved, ordering, layout, etc.
Under the hood, the elements/related_listings.thtml template is called and there we make a programatic request to show listings module/widget. Since we are calling it manually, we need to pass all the settings directly, otherwise it will use any existing defaults.
You can see all of the available settings if you open the related_listings.thtml.
Just another quick example below to include a category filter and number of results.
<h2>Restaurants & Hotels in <?php echo $CustomFields->field('jr_city',$listing,false,false); ?></h2>
<?php
echo $this->element('related_listings',[
'field' => 'jr_city',
'listing_order' => 'rating',
'category' => [23, 24], // Array of category IDs
'themelayout' => 'vertical',
'orientation' => 'native-scroll',
'total' => 6,
'limit' => 6
]);
?>
If you want to automatically show listings in the same category as the current listings, you can get the category ID for the current listing and pass it to the category option.
<?php
echo $this->element('related_listings',[
'field' => 'jr_city',
'listing_order' => 'rating',
'category' => $listing['Category']['cat_id'],
'themelayout' => 'vertical',
'orientation' => 'native-scroll',
'total' => 6,
'limit' => 6
]);
?>
Theme Suffix
If you need to use a custom template for the related listings, you can pass a theme suffix as an optional parameter, then copy the modules/listings.thtml template to your overrides with the corresponding suffix.
For example, to use the _related suffix:
<?php
echo $this->element('related_listings',[
'field' => 'jr_city',
'suffix' => '_related',
]);
?>
Above we are using the elements/related_listings.thtml as a shortcut because in that template were using the passed related listing custom field and constructing a custom conditional for the module/widget.
However, if you want to programatically display the listings module/widget without the related listings feature you can do that as well and continue to have access to all the settings available via the administration setup.
The code with all parameters looks like this:
$params = [
'module_id'=>rand(1000,10000),
'module' => [
'themelayout' => $themelayout ?? '',
'listing_order' => $listing_order ?? 'rdate', // rdate|rating|rrating|topratededitor|raviews|random|featuredrandom|rhits|proximity
'summary'=> $summary ?? 0, // Show summary
'summary_words'=>'10',
'show_category'=> $show_category ?? 1, // Show category
'fields'=> $fields ?? '', // Comma separated list of custom fields to show (i.e. jr_state,jr_city)
'editor_rating'=> $editor_rating ?? 0, // Show editor
'user_rating'=> $user_rating ?? 0, // Show user
'tmpl_suffix' => $suffix ?? '', // Theme suffix
'hide_empty' => $hide_empty ?? 1,
'custom_lat' => $custom_lat ?? '',
'custom_lon' => $custom_lon ?? '',
'radius' => $radius ?? '',
'distance' => $distance ?? 1,
'tn_show'=> $tn_show ?? 1, // Show thumbnail
'tn_position'=>$tn_position ?? 'left', // left|right|top|bottom
'tn_mode'=> $tn_mode ?? 'crop', // Thumbnail type. Valid options scale|crop
'tn_size'=> $tn_size ?? '100x100', // Thumbnail width
'extension' => 'com_content',
'cat_auto' => $cat_auto ?? 0, // Cateogry auto-detect
'dir' => $dir ?? '', // Directory filter
'category' => $category ?? '', // Category filter
'listing' => '', // Listing filter
'exclude_dirid' => $exclude_dirid ?? '',
'custom_where' => $custom_where,
'custom_order' => $order ?? $custom_order ?? '',
'nav_position' => $nav_position ?? 'bottom',
'orientation' => $orientation ?? 'horizontal', // horizontal|vertical|fade,
'orientation_mobile' => $orientation_mobile ?? 'native-scroll',
'slideshow' => $slideshow ?? false,
'slideshow_interval' => $slideshow_interval ?? 6,
'module_total' => $total, // Max. number of results
'module_limit' => $limit, // Results per page
'columns' => $columns, // Number of columns
'module_total_mobile' => (int) $total_mobile, // Max. number of results
'module_limit_mobile' => (int) $limit_mobile, // Results per page
'columns_mobile' => (int) $columns_mobile, // Number of columns
'show_numbers'=> $show_numbers ?? 0,
'filter_listing_period'=>'', // Filter: Listings submitted in past x days
'filter_review_period'=>'', // Filter: Listings with reviews submitted in past x days
'filter_review_count'=>'', // Filter: Listings with review count higher than
'filter_avg_rating'=>'', // Filter: Listings with average rating higher than
'compare'=> $compare ?? 0, // Show compare button
'moduleclass_sfx' => '' // Module suffix
]
];
echo $this->requestAction('module_listings/index',$params);
?>
You can use this approach to embed listings in JReviews template and pass the parameters you want.
Alternatively, the listings shortcode is a much simpler method to achieve the same results, although you can't use custom_where and custom_order settings with the shortcode for security reasons.