Related Listings

Overview

Related listings can be shown in listing detail pages through widgets, that can be setup directly in each listing type.

In addition to the related listing widgets, you can also show listings through shortcodes and template customizations.

Some of the relation types require the use of a related listing custom field. This field type can also be used standalone, without the need for widgets.

By using a related listing custom field, you allow users posting listings on your site to create direct, and indirect, relations for those listings.

When a listing is created or updated, it's possible to lookup existing listings within the custom field and select them. When the listing is saved, the selected listing titles will appear in the custom field output and link back to the listing. You can see an example on the demo site where Venue is a related listing custom field in Events, and it links back to the Venue listing.

When creating a related listing custom field, you can adjust the settings to:

  • Filter suggestions by listing type
  • Filter suggestions by category
  • Filter suggestions to listings owned by the logged in user
  • Change the sorting order for suggestions
  • Limit the number of options that can be selected

Detail Page Widgets

There are many types of relations, some requiring a bit more setup than others.

When you create or update a listing type you'll find a Detail Page Widgets tab where you can create up to 10 related listing widgets for a single listing.

There are many possible setups with lots of different permutations, so we'll cover the basics to help you get started.

This is the list of the related listing options available via related listing widgets:

Proximity Filter

If you use the MapsPro Add-on or the GeoMaps Add-on, you can automatically filter listings shown in the related listing widgets to listings that are in proximity to the current listing.

This feature works for all the related listing options and can be enabled by changing the Listing Ordering setting to Proximity.

You can also adjust the radius that you want to use for proximity filtering.

Synchronous vs. Asynchronous Loading

By default the widgets load asynchronously. This means that a separate request is made for each widget to load the data, only after the page finishes loading. This is good when it comes to page loading speeds, because less database queries and code need to be processed during the intial page load. It also allows you to show the widgets anywhere on the page as explained in the next section.

If you want to be sure that the related listings info is seen as being a part of the listing for SEO-puposes, you may want to disable the asynchronous feature for some of your widgets. You can do that by toggling off the Load Asynchronously setting.

It all comes down to performance vs indexability and when it comes to Google, testing is the only way to find out what works best for SEO.

Custom Placement

When a widget is set to load asynchrously, you also have the option of showing the widget output anywhere on the page instead of the default placement.

There are two settings that allow you to control the placement:

  1. Target Element ID
  2. Target Element Class

These refer to the HTML attributes of an element.

<div id="some-id" class="some-class"></div>

You need to use one, or the other, not both. By default all widgets use the Target Element ID which is set to jrRelatedListings. Because the listing detail template already has a div element with that ID attribute, all widget are placed there.

Some ideas for placing widgets in custom locations on the listing detail page:

  • Load a widget in a sidebar using a Joomla HTML Module or WordPress HTML widget to create an empty div with a custom id or class attribute that matches the value you add to the above settings
  • Load a widget within a banner custom fields where you add the empty div inside the banner description
  • Load a widget anywhere in the listing detail template by adding the empty div to the template itself.

Widget Template Customization

The listing widgets use the same template as the JReviews listings Joomla module and WordPress widget, so you can customize their template as explained in template overrides.

The same is true for using theme suffixes for which there is a setting in each widget.

For example, if you use a _hotels suffix, you would place the template override in your custom theme in the following structure:

`-- mysite/
    |-- themeInfo.xml
    `-- modules/
        `-- listings_hotels.thtml

Advanced Filters

If you need more advanced options to control the results of a related listing widget, you can also use the Custom Where and Custom Order settings. You can learn more about using these settings in Custom Lists.