Difference between revisions of "Listings Module"

From JReviews Documentation
Jump to: navigation, search
 
(4 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
The Listings Module can be used for displaying:
 
The Listings Module can be used for displaying:
*Latest Listings
 
*Top User Rated Listings
 
*Worst User Rated Listings
 
*Top Editor Rated Listings
 
*Most Reviewed Listings
 
*Random Listings
 
*Featured Random Listings
 
*Popular Listings
 
  
 +
* Latest Listings
 +
* Top User Rated Listings
 +
* Worst User Rated Listings
 +
* Top Editor Rated Listings
 +
* Most Reviewed Listings
 +
* Random Listings
 +
* Featured Random Listings
 +
* Popular Listings
 +
* Listings in proximity to the current listing (detail pages only)
  
== Example of the module layout ==
+
__TOC__
  
[[File:ListingsModule.png]]
+
'''Example of the module layout:'''
  
*the module displays listing's thumbnail, title, category, editor and user rating.
+
[[File:listings-module.png]]
*to modify the layout, the theme file of the Listings Module is located here:  
+
**<span style="color: blue">\com_jreviews\jreviews\views\themes\default\modules\listings.thtml</span>
+
  
 +
== Listings Module Parameters ==
  
== Module's Parameters ==
+
[[File:listings-module-params1.png]]
[[File:ListingsModuleParameters1.png]]
+
*'''Everywhere Extension''' - This is a universal module that works not only with core JReviews  listings, but also with 3rd party components integrated via the [[JReviews Everywhere Add-on|Everywhere Add-on]]. The module can only display listings from one component at a time, so you need to enter the component's name here (i.e. com_content, com_sobi2, com_k2, etc.)
+
*'''Custom WHERE''' - custom where for query (i.e Field.jr_brand LIKE '%Canon%')
+
*'''Custom ORDER BY''' - overrides listing ordering (i.e Field.jr_brand DESC)
+
  
 +
'''Listings Ordering''' - choose what the module will display:
  
[[File:ModuleParametersSuffix.png]]
+
* ''Latest Listings (everywhere)''
*'''JReviews Template Suffix''' - this parameter allows you to use a different theme file for each published instance of the module.
+
* ''Top User Rated (everywhere)''
*'''Module Class Suffix''' - a suffix will be applied to the CSS class of the module. This allows individual module styling.
+
* ''Worst User Rated (everywhere)''
 +
* ''Top Editor Rated (com_content)''
 +
* ''Most Reviewed (everywhere)''
 +
* ''Random (everywhere)''
 +
* ''Featured Random (com_content)''
 +
* ''Popular (com_content)''
 +
* ''Proximity (com_content) requires GeoMaps Add-on'' - works only on listing detail pages and displays listings in proximity to the current listing.
  
 +
'''Radius for Proximity Ordering''' - used if Proximity is selected in Listing Ordering parameter.
  
[[File:ModuleParametersPagination.png]]
+
'''Show Distance for Proximity Ordering''' - used if Proximity is selected in Listing Ordering parameter.
*'''Enable Ajax Pagination''' - allows users to navigate to other pages inside the module without page reloads
+
*'''Plugin width (px)''' - required only when Ajax Pagination is enabled
+
*'''Plugin height (px)''' - required only when Ajax Pagination is enabled
+
*'''Limit results''' - sets the number of results shown in the module
+
*'''Columns''' - number of columns or items per row to show
+
  
 +
'''Show Summary''' - here you can enable displaying listing summary text in the module.
  
[[File:ModuleParametersCats.png]]
+
'''Summary Words''' - how many words of the summary text to show.
*'''Category Autodetect''' - JReviews will try to determine the category id and show only results for that category. If enabled, this setting overrides all the ID settings below it.
+
*'''To use filtering by IDs you must enter "com_content" in the Everywhere extension parameter'''
+
  
 +
'''Show Listing Category''' - here you can enable displaying the listing category.
  
[[File:ModuleParametersThumb.png]]
+
'''Comma separated list of custom fields to show (i.e. jr_state,jr_city)''' - enter the names of custom fields that you want to show in the module.
*'''Thumbnail Type''' - Scale creates thumbnail with specified width. Height is scaled proportionately. Crop takes a square from the center of the image and scales to the specified width
+
  
 +
'''Show Editor Rating''' - here you can enable displaying the editor rating.
  
[[File:ListingsModuleParameters2.png]]
+
'''Show User Rating''' - here you can enable displaying the user rating.
*'''Filter: Listings submitted in past x days''' - filter the results to use listings submitted in the past x days
+
*'''Filter: Listings with reviews submitted in past x days''' - filter the results to use reviews submitted in the past x days
+
*'''Filter: Listings with review count higher than''' - filter the results to listings having at least the defined number of reviews
+
*'''Filter: Avg rating higher than''' - filter the results to listings with rating higher than the defined number
+
  
 +
'''JReviews Theme Suffix''' - this suffix will be applied to the module view file and is useful to create multiple instances of the module that have different outputs. Two alternative theme files with suffixes for the Listings Module come by default with JReviews: _slideshow and _vertical.
 +
 +
[[File:listings-module-params2.png]]
 +
 +
'''Show Thumbnail''' - enable or disable displaying the main media thumbnail.
 +
 +
'''Thumbnail Position''' - (Left | Right | Top | Bottom)
 +
 +
'''Thumbnail Mode''' - (Scale | Crop)
 +
 +
'''Size (WIDTHxHEIGHT)''' - WIDTHxHEIGHT in pixels. This can be considered as &quot;maximum width&quot; and &quot;maximum height&quot; for the thumbnail.
 +
 +
[[File:listings-module-params3.png]]
 +
 +
'''Everywhere Extension''' - this is a universal module that works not only with core JReviews listings, but also with 3rd party components integrated via the Everywhere Add-on. The module can only display listings from one component at a time, so you need to enter the component's name here (i.e. com_content, com_sobi2, com_k2, etc.)
 +
 +
'''Category Autodetect''' - JReviews will try to determine the category id and show only results for that category. If enabled, this setting overrides all the ID settings below it.
 +
 +
'''Directory IDs (com_content)''' - filter listings by directory IDs.
 +
 +
'''Category IDs (everywhere)''' - filter listings by category IDs.
 +
 +
'''Listing IDs (everywhere)''' - display listings based on specific listing IDs.
 +
 +
[[File:listings-module-params4.png]]
 +
 +
With '''Custom WHERE''' and '''Custom ORDER BY''' parameters you can display listings based on the custom sql commands. [http://docs.reviewsforjoomla.com/?title=Using_Custom_WHERE_and_Custom_ORDER_BY_parameters Read about Custom WHERE and Custom ORDER BY].
 +
 +
[[File:listings-module-params5.png]]
 +
 +
'''Positioning of Pagination''' - choose the position of slider arrows when the module has multiple slider pages.
 +
 +
'''Page Transition''' - choose the transition type for the slider pagination (Horizontal sliding | Vertical sliding | Fade effect).
 +
 +
'''Enable Slideshow''' - if enabled, the module will automatically advance slider pages.
 +
 +
'''Slideshow Interval (sec.)''' - time between pages in seconds.
 +
 +
'''Max. number of results''' - total number of results that will be displayed.
 +
 +
'''Results per page''' - how many results will be displayed per slider page. If you enter the same number as for ''Max. number of results'', then the module slider will be disabled and all results will be displayed at once.
 +
 +
'''Columns''' - choose how many results per row to show.
 +
 +
'''Show numbers''' - adds numbers before each result.
 +
 +
[[File:listings-module-params6.png]]
 +
 +
'''Submitted in past x days''' - with this setting you can filter the results to use listings submitted in the past x days. The setting works for all modes.
 +
 +
'''With reviews submitted in past x days''' - will display listings that had reviews submitted in the past x days.
 +
 +
'''Review count higher than''' - filters the results to listings with having at least the defined number of reviews.
 +
 +
'''Avg rating higher than''' - filters the results to listings with having at least the defined average rating.
 +
 +
[[File:listings-module-params7.png]]
 +
 +
'''Enable Compare Button''' - displays the ''Compare'' button in listings (only if listing comparison is enabled in global JReviews configuration as well).
 +
 +
== Alternative Layouts of the Listings Module ==
 +
 +
'''Example of the _slideshow layout:'''
 +
 +
[[File:listings-module-slideshow.png]]
 +
 +
To use this layout, enter &quot;_slideshow&quot; in the '''Theme Suffix''' parameter.
 +
 +
'''Example of the _vertical layout:'''
 +
 +
[[File:listings-module-vertical.png]]
 +
 +
To use this layout, enter &quot;_vertical&quot; in the '''Theme Suffix''' parameter.
 +
 +
== Customizing the Listings Module ==
 +
 +
If you want to customize the theme file of the Listings Module, this is its default location:
 +
 +
*<span style="color: blue">/com_jreviews/jreviews/views/themes/default/modules/listings.thtml</span>
 +
 +
Before you start customizing the theme files, make sure you read about [[JReviews Code Overrides]] functionality and create a custom theme.
 +
 +
There are two alternative theme files for the Listings Module:
 +
 +
*<span style="color: blue">/com_jreviews/jreviews/views/themes/default/modules/listings_slideshow.thtml</span>
 +
*<span style="color: blue">/com_jreviews/jreviews/views/themes/default/modules/listings_vertical.thtml</span>
 +
 +
To use one of those, enter the theme file suffix in the '''Theme Suffix''' parameter. The same way you can create multiple custom copies of the Listings Module theme file. Remember to clear JReviews File Registry when creating new theme files.
  
  

Latest revision as of 10:28, 9 November 2016

The Listings Module can be used for displaying:

  • Latest Listings
  • Top User Rated Listings
  • Worst User Rated Listings
  • Top Editor Rated Listings
  • Most Reviewed Listings
  • Random Listings
  • Featured Random Listings
  • Popular Listings
  • Listings in proximity to the current listing (detail pages only)

Example of the module layout:

Listings-module.png

Listings Module Parameters

Listings-module-params1.png

Listings Ordering - choose what the module will display:

  • Latest Listings (everywhere)
  • Top User Rated (everywhere)
  • Worst User Rated (everywhere)
  • Top Editor Rated (com_content)
  • Most Reviewed (everywhere)
  • Random (everywhere)
  • Featured Random (com_content)
  • Popular (com_content)
  • Proximity (com_content) requires GeoMaps Add-on - works only on listing detail pages and displays listings in proximity to the current listing.

Radius for Proximity Ordering - used if Proximity is selected in Listing Ordering parameter.

Show Distance for Proximity Ordering - used if Proximity is selected in Listing Ordering parameter.

Show Summary - here you can enable displaying listing summary text in the module.

Summary Words - how many words of the summary text to show.

Show Listing Category - here you can enable displaying the listing category.

Comma separated list of custom fields to show (i.e. jr_state,jr_city) - enter the names of custom fields that you want to show in the module.

Show Editor Rating - here you can enable displaying the editor rating.

Show User Rating - here you can enable displaying the user rating.

JReviews Theme Suffix - this suffix will be applied to the module view file and is useful to create multiple instances of the module that have different outputs. Two alternative theme files with suffixes for the Listings Module come by default with JReviews: _slideshow and _vertical.

Listings-module-params2.png

Show Thumbnail - enable or disable displaying the main media thumbnail.

Thumbnail Position - (Left | Right | Top | Bottom)

Thumbnail Mode - (Scale | Crop)

Size (WIDTHxHEIGHT) - WIDTHxHEIGHT in pixels. This can be considered as "maximum width" and "maximum height" for the thumbnail.

Listings-module-params3.png

Everywhere Extension - this is a universal module that works not only with core JReviews listings, but also with 3rd party components integrated via the Everywhere Add-on. The module can only display listings from one component at a time, so you need to enter the component's name here (i.e. com_content, com_sobi2, com_k2, etc.)

Category Autodetect - JReviews will try to determine the category id and show only results for that category. If enabled, this setting overrides all the ID settings below it.

Directory IDs (com_content) - filter listings by directory IDs.

Category IDs (everywhere) - filter listings by category IDs.

Listing IDs (everywhere) - display listings based on specific listing IDs.

Listings-module-params4.png

With Custom WHERE and Custom ORDER BY parameters you can display listings based on the custom sql commands. Read about Custom WHERE and Custom ORDER BY.

Listings-module-params5.png

Positioning of Pagination - choose the position of slider arrows when the module has multiple slider pages.

Page Transition - choose the transition type for the slider pagination (Horizontal sliding | Vertical sliding | Fade effect).

Enable Slideshow - if enabled, the module will automatically advance slider pages.

Slideshow Interval (sec.) - time between pages in seconds.

Max. number of results - total number of results that will be displayed.

Results per page - how many results will be displayed per slider page. If you enter the same number as for Max. number of results, then the module slider will be disabled and all results will be displayed at once.

Columns - choose how many results per row to show.

Show numbers - adds numbers before each result.

Listings-module-params6.png

Submitted in past x days - with this setting you can filter the results to use listings submitted in the past x days. The setting works for all modes.

With reviews submitted in past x days - will display listings that had reviews submitted in the past x days.

Review count higher than - filters the results to listings with having at least the defined number of reviews.

Avg rating higher than - filters the results to listings with having at least the defined average rating.

Listings-module-params7.png

Enable Compare Button - displays the Compare button in listings (only if listing comparison is enabled in global JReviews configuration as well).

Alternative Layouts of the Listings Module

Example of the _slideshow layout:

Listings-module-slideshow.png

To use this layout, enter "_slideshow" in the Theme Suffix parameter.

Example of the _vertical layout:

Listings-module-vertical.png

To use this layout, enter "_vertical" in the Theme Suffix parameter.

Customizing the Listings Module

If you want to customize the theme file of the Listings Module, this is its default location:

  • /com_jreviews/jreviews/views/themes/default/modules/listings.thtml

Before you start customizing the theme files, make sure you read about JReviews Code Overrides functionality and create a custom theme.

There are two alternative theme files for the Listings Module:

  • /com_jreviews/jreviews/views/themes/default/modules/listings_slideshow.thtml
  • /com_jreviews/jreviews/views/themes/default/modules/listings_vertical.thtml

To use one of those, enter the theme file suffix in the Theme Suffix parameter. The same way you can create multiple custom copies of the Listings Module theme file. Remember to clear JReviews File Registry when creating new theme files.