View source for JReviews:Developers Filters

JReviews 3 comes with Filters that allow you to make certain types of customizations and extend the functionality of JReviews without having to modify core files.

<div class="toclimit-3">__TOC__</div>


= What is a Filter? = 

JReviews has many filter hooks strategically placed in the code at points where you may want to change or override the value of a variable at runtime.

Filters can modify data by binding a callback function to a filter hook. When the filter is executed, each callback function is run in order of priority, and can modify the filtered data by returning a new value.

For example, you can use a filter to:

* Change the page title and metatags of different pages
* Override the permissions of specific users or user groups for different events (creating listings, reviews, etc.)
* Add or remove CSS and Scripts to and from the page.

= Defining a new Filter Hook =

JReviews 3 already comes with many filter hooks and we'll add more over time. However, if you need to create a new filter that is not yet available you would use the following syntax:

<source lang="php">
$data = \Clickfwd\Hook\Filter::filter('example_filter_name', $data, ['foo'=>$bar]);
</source>

Where:

* $data is the variable that can be modified by filter callback function
* $params are other arguments that can be passed to the filter callback function to provide context and their values cannot be modified by the filter.

= Using Filter Functions =

The following example shows how a callback function is bound to a filter hook:

<source lang="php">
function example_filter_callback_function($data, $params = [])
{
   // Modify $data in some way and return it
   return $data;
}

Clickfwd\Hook\Filter::add('example_filter_name', 'example_filter_callback_function', $priority = 10);
</source>

'''The $data variable can be modified inside the callback function and must always be returned at the end of the function.'''

To create new filter functions that are not overwritten on upgrades, create a new file in overrides and place your filter functions there:

'''Joomla'''

<pre>/templates/jreviews_overrides/filters/filter_functions.php</pre>

'''WordPress'''

<pre>/jreviews_overrides/filters/filter_functions.php</pre>

= Available Filters =

== Notifications ==

=== Listing Inquiry Email Payload ===

==== Description ====

The "modify_inquiry_sender_info" filter is used to filter the inquiry email payload before the email is sent. 

==== Usage ====

When the "modify_inquiry_sender_info" filter is called, it is passed two arguments. The first argument is an associative array with the email payload ($to, $bcc, $fromEmail, $fromName, $subject, $body). The second argument is an associative array with context data for the $listing and $event that triggered the email. $event is an object that allows retrieving sender user ID and IP address information.

==== Examples ====

===== Modify sender name and email =====

By default when an inquiry email is sent, the sender name and e-mail address are populated with the information entered in the inquiry form. This allows the recipient of the inquiry to reply directly to the sender. However, in some cases, you may not want the recipient to reply directly to the sender and you can use this filter to modify the email values before it is sent.

<source lang="php">
function modify_inquiry_sender_info($payload)
{
   $payload['fromEmail'] = 'john.smith@domain.com';

   $payload['fromName'] = 'John Smith';

   return $payload;
}

Clickfwd\Hook\Filter::add('listing_inquiry_email_payload', 'modify_inquiry_sender_info', 10);
</source>

== Asset Manager ==

=== Asset Manager Stylesheets ===

==== Description ====

The "asset_manager_stylesheets" filter is used to filter the stylesheets loaded by JReviews and Add-ons. 

==== Usage ====

When the "asset_manager_stylesheets" filter is called, it is passed an associative array containing the paths of the stylesheets that will be loaded on the page. The array contains keys for different namespaces used to load stylesheets so it's possible to control the order in which these are loaded. The namespaces are: addon, core, bottom, and top.

==== Examples ====

===== Unload jQuery UI Stylesheet =====

It is possible to stop specific stylesheets from loading if you want to use your own stylesheets or have already overwritten them in your site's stylesheet.

<source lang="php">
function remove_stylesheets($stylesheets)
{
  // dd($stylesheets); // If you uncomment this line and refresh the page, you'll be able to see the contents of the $css array to find out the path you can use to unload a stylesheet
  unset($stylesheets['core']['jquery_ui_theme/jquery-ui-1.9.2.custom.css']);

  return $stylesheets;
}

Clickfwd\Hook\Filter::add('asset_manager_stylesheets', 'remove_stylesheets', 10);
</source>

=== Asset Manager Scripts ===

==== Description ====

The "asset_manager_scripts" filter is used to filter the scripts loaded by JReviews and Add-ons. 

==== Usage ====

When the "asset_manager_scripts" filter is called, it is passed an associative array containing the paths of the scripts that will be loaded on the page. The array contains keys for different namespaces used to load scripts so it's possible to control the order in which these are loaded. The namespaces are: addon, core, bottom, and top.

==== Examples ====

===== Unload bxSlider Script =====

<source lang="php">
function remove_scripts($scripts)
{
  // dd($scripts); // If you uncomment this line and refresh the page, you'll be able to see the contents of the $scripts array to find out the path you can use to unload a script
  unset($jsArray['top']['bxslider-4/jquery.bxslider.min.js']);

  return $scripts;
}

Clickfwd\Hook\Filter::add('asset_manager_scripts', 'remove_scripts', 10);
</source>

== Metatags ==

=== Page Title === 

==== Description ====

The "page_title_metatag" filter is used to filter page title tag. 

==== Usage ====

When the "page_title_metatag" filter is called, it is passed two arguments. The first argument is the page title. The second argument is an associative array with context data.

<source lang="php">
function page_title_tag($title, $params)
{
  // Uncomment line below to dump title and context data to screen
  // dd($title, $params); 

  return $title;
}

Clickfwd\Hook\Filter::add('page_title_metatag', 'page_title_tag', 10);
</source>


=== Page Robots Metatag === 

==== Description ====

==== Usage ====

  160:    $robots = Hook::filter('page_robots_metatag', $robots, $params);

=== Page Keywords Metatag === 

==== Description ====

==== Usage ====

  202:    $keywords = Hook::filter('page_keywords_metatag', $keywords, $params);

=== Page Description Metatag === 

==== Description ====

==== Usage ====

  214:    $description = Hook::filter('page_description_metatag', $description, $params);

=== Page Canonical Metatag === 

==== Description ====

==== Usage ====

  226:    $canonical = Hook::filter('page_canonical_metatag', $canonical, $params);

=== Page Prev Metatag === 

==== Description ====

==== Usage ====

  238:    $prev = Hook::filter('page_prev_metatag', $prev, $params);

=== Page Next Metatag === 

==== Description ====

==== Usage ====

  248:    $next = Hook::filter('page_next_metatag', $next, $params);

== Listing Detail ==

=== Listing Detail Action Buttons ===

==== Description ====

==== Usage ====

  541:    $menuExtras = Clickfwd\Hook\Filter::filter('listing_detail_action_buttons', $menuExtras, [['listing'=>$listing]]);

== Listing Permissions ==

=== Trusted On Listing Create ===

==== Description ====

==== Usage ====

   57:    return $this->filteredResponse($trust,'trusted_on_create_listing');

=== Listing Allows Claims ===

==== Description ====

==== Usage ====

   85:    return $this->filteredResponse($permission,'listing_allows_claims',$listing);

=== Listing Allows Inquiries ===

==== Description ====

==== Usage ====

  132:    return $this->filteredResponse($permission,'listing_allows_inquiries',$listing);


=== Listing Allows Favorites ===

==== Description ====

==== Usage ====

  150:    return $this->filteredResponse($permission,'listing_allows_favorites',$listing);

=== Listing Allows User Reviews ===

==== Description ====

==== Usage ====

  173:    return $this->filteredResponse($permission,'listing_allows_user_reviews',$listing);

=== Listing Allows Editor Reviews ===

==== Description ====

==== Usage ====

  191:    return $this->filteredResponse($permission,'listing_allows_editor_reviews',$listing);

=== Listing User Reviews Open ===

==== Description ====

==== Usage ====

  207:    return $this->filteredResponse($permission,'listing_user_reviews_opened',$listing);

=== Listing Editor Reviews Open ===

==== Description ====

==== Usage ====

  223:    return $this->filteredResponse($permission,'listing_editor_reviews_opened',$listing);

=== Can Create Listing ===

==== Description ====

==== Usage ====

  251:    $permission = $this->filteredResponse($permission,'can_create_listing',[$listingTypeId]);

=== Can Update Listing ===

==== Description ====

==== Usage ====

  278:    return $this->filteredResponse($permission,'can_update_listing',$listing);

=== Can Add Listing Metadata ===

==== Description ====

==== Usage ====

  296:    return $this->filteredResponse($permission,'can_add_listing_metadata',$listingType);

=== Can User WYSIWYG Editor in Listing ===

==== Description ====

==== Usage ====

  312:    return $this->filteredResponse($permission,'can_use_editor_in_listing',[]);

=== Can Publish Listing ===

==== Description ====

==== Usage ====

  334:    return $this->filteredResponse($permission,'can_publish_listing',$listing);

=== Can Delete Listing ===

==== Description ====

==== Usage ====

  356:    return $this->filteredResponse($permission,'can_delete_listing',$listing);

=== Can Claim Listing ===

==== Description ====

==== Usage ====

  374:    return $this->filteredResponse($permission,'can_claim_listing',$listing);
  
=== Can Send Listing Inquiry ===

==== Description ====

==== Usage ====

  390:    return $this->filteredResponse($permission,'can_send_listing_inquiry',$listing);
  
=== Can Favorite Listing ===

==== Description ====

==== Usage ====

  406:    return $this->filteredResponse($permission,'can_favorite_listing',$listing);
  
=== Can Feature Listing ===

==== Description ====

==== Usage ====

  420:    return $this->filteredResponse($permission,'can_feature_listing',[]);

=== Can Create User Review For Listing ===

==== Description ====

==== Usage ====

  496:    return $this->filteredResponse($permission,'can_create_user_review_for_listing',$listing,$this->getMessage());

=== Can Create Editor Review For Listing ===

==== Description ====

==== Usage ====

  546:    return $this->filteredResponse($permission,'can_create_editor_review_for_listing',$listing,$this->getMessage());

=== Can Add Review on Listing Create ===

==== Description ====

==== Usage ====

  564:    return $this->filteredResponse($permission,'can_add_review_on_listing_create',$listingType);

=== Can Update Listing Media ===

==== Description ====

==== Usage ====

  586:    return $this->filteredResponse($permission,'can_update_listing_media',[$listing,$listingType]);

=== Can Upload Listing Media ===

==== Description ====

==== Usage ====

  624:    return $this->filteredResponse($permission,'can_upload_listing_media',[$listing,$listingType]);

=== Can Upload Listing Media From URL ===

==== Description ====

==== Usage ====

  644:    return $this->filteredResponse($permission,'can_upload_media_from_url_in_listing',$listing);

=== Can Upload Listing Photo ===

==== Description ====

==== Usage ====

  662:    return $this->filteredResponse($permission,'can_upload_listing_photo',[$listing,$listingType]);

=== Can Upload Listing Video ===

==== Description ====

==== Usage ====

  680:    return $this->filteredResponse($permission,'can_upload_listing_video');

=== Can Upload Listing Audio ===

==== Description ====

==== Usage ====

  698:    return $this->filteredResponse($permission,'can_upload_listing_audio',[$listing,$listingType]);

=== Can Upload Listing Attachment ===

==== Description ====

==== Usage ====

  716:    return $this->filteredResponse($permission,'can_upload_listing_attachment',[$listing,$listingType]);

== Media Permissions ==

=== Trusted On Create Photo ===

==== Description ====

==== Usage ====

   30:    return $this->filteredResponse($trust,'trusted_on_create_photo');

=== Trusted On Create Video ===

==== Description ====

==== Usage ====

   49:    return $this->filteredResponse($trust,'trusted_on_create_video');

=== Trusted On Create Audio ===

==== Description ====

==== Usage ====

   68:    return $this->filteredResponse($trust,'trusted_on_create_audio');

=== Trusted On Create Attachment ===

==== Description ====

==== Usage ====

   87:    return $this->filteredResponse($trust,'trusted_on_create_attachment');

=== Media Allows Voting ===

==== Description ====

==== Usage ====

  105:    return $this->filteredResponse($permission,'media_allows_voting',$listing);

=== Media Allows Report ===

==== Description ====

==== Usage ====

  121:    return $this->filteredResponse($permission,'media_allows_report',$listing);

=== Can Update Media In Listing ===

==== Description ====

==== Usage ====

  149:    return $this->filteredResponse($permission,'can_update_media_in_listing',[$listing,$media]);

=== Can Delete Media In Listing ===

==== Description ====

==== Usage ====

  177:    return $this->filteredResponse($permission,'can_delete_media_in_listing',[$listing,$media]);

=== Can Publish Media In Listing ===

==== Description ====

==== Usage ====

  205:    return $this->filteredResponse($permission,'can_publish_media_in_listing',[$listing,$media]);

=== Can Set Main Media ===

==== Description ====

==== Usage ====

  237:    return $this->filteredResponse($permission,'can_set_main_media',[$listing,$media]);

=== Can Update Media Details ===

==== Description ====

==== Usage ====

  259:    return $this->filteredResponse($permission,'can_update_media_details',[$listing,$media]);

=== Can Vote on Media ===

==== Description ====

==== Usage ====

  286:    return $this->filteredResponse($permission,'can_vote_on_media',[$listing,$media]);

=== Can Report Media ===

==== Description ====

==== Usage ====

  302:    return $this->filteredResponse($permission,'can_report_media',$listing);

=== Can Download Attachment ===

==== Description ====

==== Usage ====

  323:    return $this->filteredResponse($permission,'can_download_attachment',$media);

== Review Permissions ==

=== Trusted on Create User Review ===

==== Description ====

==== Usage ====

   28:    return $this->filteredResponse($trust,'trusted_on_create_user_review');

=== Trusted on Update User Review ===

==== Description ====

==== Usage ====
   45:    return $this->filteredResponse($trust,'trusted_on_update_user_review');

=== Trusted on Create Editor Review ===

==== Description ====

==== Usage ====

   58:    return $this->filteredResponse($trust,'trusted_on_create_editor_review');

=== Trusted on Update Editor Review ===

==== Description ====

==== Usage ====

   71:    return $this->filteredResponse($trust,'trusted_on_update_editor_review');

=== Trusted on Create Review Owner Reply ===

==== Description ====

==== Usage ====

   84:    return $this->filteredResponse($trust,'trusted_on_create_review_owner_reply');

=== Review Allows Report ===

==== Description ====

==== Usage ====

  104:    return $this->filteredResponse($permission,'review_allows_report',$review);

=== Review Allows Voting ===

==== Description ====

==== Usage ====

  124:    return $this->filteredResponse($permission,'review_allows_voting',$review);

=== Review Allows Replies ===

==== Description ====

==== Usage ====

  140:    return $this->filteredResponse($permission,'review_allows_replies',$review);

=== Review Allows Discussions ===

==== Description ====

==== Usage ====

  156:    return $this->filteredResponse($permission,'review_allows_discussions',$review);

=== Can Update Review ===

==== Description ====

==== Usage ====

  180:    return $this->filteredResponse($permission,'can_update_review',$review);

=== Can Reply To Review ===

==== Description ====

==== Usage ====

  204:    return $this->filteredResponse($permission,'can_reply_to_review',[$listing,$review]);

=== Can Delete Review Reply ===

==== Description ====

==== Usage ====

  220:    return $this->filteredResponse($permission,'can_delete_review_reply',$listing);

=== Can Report Review ===

==== Description ====

==== Usage ====

  236:    return $this->filteredResponse($permission,'can_report_review',$review);

=== Can Vote On Review ===

==== Description ====

==== Usage ====

  261:    return $this->filteredResponse($permission,'can_vote_on_review',$review);

=== Can Create Review Comment ===

==== Description ====

==== Usage ====

  279:    return $this->filteredResponse($permission,'can_create_review_post',$review);

=== Can Upload Review Media ===

==== Description ====

==== Usage ====

  319:    return $this->filteredResponse($permission,'can_upload_review_media',$review);

=== Can Upload Review Media From URL ===

==== Description ====

==== Usage ====

  337:    return $this->filteredResponse($permission,'can_upload_media_from_url_in_review',$review);

=== Can Upload Review Photo ===

==== Description ====

==== Usage ====

  353:    return $this->filteredResponse($permission,'can_upload_review_photo',$review);

=== Can Upload Review Video ===

==== Description ====

==== Usage ====

  369:    return $this->filteredResponse($permission,'can_upload_review_video',$review);

=== Can Upload Review Audio ===

==== Description ====

==== Usage ====

  385:    return $this->filteredResponse($permission,'can_upload_review_audio',$review);

=== Can Upload Review Attachment ===

==== Description ====

==== Usage ====

  401:    return $this->filteredResponse($permission,'can_upload_review_attachment',$review);

== Review Discussion Permissions ==

=== Trusted on Create Review Discussion ===

==== Description ====

==== Usage ====

   26:    return $this->filteredResponse($trust,'trusted_on_create_review_discussion');

=== Review Discussion Allows Report ===

==== Description ====

==== Usage ====

   48:    return $this->filteredResponse($permission,'review_discussion_allows_report',$post);

=== Can Report Review Discussion ===

==== Description ====

==== Usage ====

   64:    return $this->filteredResponse($permission,'can_report_review_discussion',$post);

=== Can Update Review Discussion ===

==== Description ====

==== Usage ====

   86:    return $this->filteredResponse($permission,'can_update_review_discussion',[$post,$review]);

=== Can Delete Review Discussion ===

==== Description ====

==== Usage ====

  108:    return $this->filteredResponse($permission,'can_delete_review_discussion',[$post,$review]);

== Field Permissions ==

=== Can View Field in Listing Detail Page ===

==== Description ====

==== Usage ====

   59:    return $this->filteredResponse($permission,'can_view_field_in_detail_page',$field);

=== Can View Field in Listing Detail Page ===

==== Description ====

==== Usage ====

   59:    return $this->filteredResponse($permission,'can_view_field_in_list_page',$field);

=== Can View Field in Listing Detail Page ===

==== Description ====

==== Usage ====

   59:    return $this->filteredResponse($permission,'can_view_field_in_comparison_page',$field);

=== Can Read Field ===

==== Description ====

==== Usage ====

   87:    return $this->filteredResponse($permission,'can_read_field',[$fname]);

=== Can Write Field ===

==== Description ====

==== Usage ====   

  115:    return $this->filteredResponse($permission,'can_write_field',[$fname]);