View source for JReviews:Developers Events

JReviews 3 comes with Events that allow you to extend the functionality of JReviews without having to modify core files.

'''This is a development feature. We provide some examples to get you started, but writing custom code for events is outside the scope of support'''

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


= What is an Event? = 

An event is an action that typically takes place after some user interaction. Each event can have one or more listeners that react to the event. Unlike [[JReviews:Developers_Filters|Filters]], events do not modify data, they only trigger other actions through event listeners.

For example, when a user submits a review, this triggers the "ReviewWasCreated" event. There are several core event listeners that listen for this particular event to:

* Send e-email notifications
* Post the review on Twitter
* Post the review on Facebook
* Post the review to the EasySocial or JomSocial activity streams (Joomla)
* Trigger native Joomla or WordPress events

Event listeners run syncronously, one after the other, so this can delay the request response time after a user performs an action, especially if any of the events send out notifications, or require communicating with external APIs like for posting to Twitter or Facebook. To improve performance, we developed an add-on that allows queing the listener actions so they can be executed asyncrously, independent of the main program flow. Please refer to the [[JReviews_Queue_Add-on|Queue Add-on]] documentation for more information.

= Using Event Listeners =

With event listeners you can execute any code after a specific event runs. Listeners are assigned to events through a ListenerProvider. For reference you can find existing listener providers with Event => Listener assigments in the following file paths:

'''Joomla'''

<pre>/components/com_jreviews/jreviews/events/providers/jreviews_listener_provider.php</pre>
<pre>/components/com_jreviews/jreviews/cms_compat/joomla/events/providers/jreviews_joomla_listener_provider.php</pre>

'''WordPress'''

<pre>/wp-content/plugins/jreviews/jreviews/events/providers/jreviews_listener_provider.php</pre>
<pre>/wp-content/plugins/jreviews/jreviews/cms_compat/wordpress/events/providers/jreviews_wordpress_listener_provider.php</pre>

You can create your own custom provider in overrides as we'll explain shortly, but if you want to override an existing provider or listener file you can also do that using [[JReviews_Code_Overrides#Overriding_JReviews_PHP_Files|JReviews Overrides]] for PHP files.

For example, if you wanted to create a listener that does something when a listing search is performed you would need to create a new entry in listener providers to assign the new listener to the "ListingSearchWasPerformed" event. Then you would need to create the listener itself. You can create new listener providers and listeners in overrides and always '''remember to clear the file registry after creating new files in overrides'''.

First we create the listener provider. This provider can contain more than one Event/Listener assignment, but for this example it will just have one.

'''Joomla'''

<pre>/templates/jreviews_overrides/events/providers/search_listener_provider.php</pre>

'''WordPress'''

<pre>/jreviews_overrides/events/providers/search_listener_provider.php</pre>

<source lang="php">
<?php
defined( 'MVC_FRAMEWORK') or die;

use Clickfwd\Listener\ListenerProvider;

class SearchListenerProvider extends ListenerProvider
{
	protected $listen = [
		'JReviews\Events\ListingSearchWasPerformed' => [
			'JReviews\Listeners\SaveListingSearchData'
		]
	];
}
</source>

Next, we create the new listener "SaveListingSearchData".

'''Joomla'''

<pre>/templates/jreviews_overrides/events/listeners/save_listing_search_data.php</pre>

'''WordPress'''

<pre>/jreviews_overrides/events/listeners/save_listing_search_data.php</pre>

<source lang="php">
<?php
namespace JReviews\Listeners;

defined( 'MVC_FRAMEWORK') or die;

use JReviews\Listeners\Traits\ListenerSetting;
use Clickfwd\Listener\QueueableListener;
use League\Event\EventInterface;

\S2App::import('ListenerTrait','listener_setting','jreviews');

class SaveListingSearchData extends QueueableListener
{
    use ListenerSetting;

    protected $queue = false;

    public function handle(EventInterface $event)
    {
	$payload = $event->getPayload();

	// Here you can introduce code that does something with the search terms, user id, etc.

	// Dump $payload to screen
	dd($payload);
    }
}
</source>

Before you can test the example, '''clear the file registry in the JReviews admin.''' This example is for illustration purposes only, so we are not actually doing anything with the search data. Instead we dump the event payload to the screen and that looks like this:

<source lang="php">
array [
  "event_user_id" => "31"
  "event_ipaddress" => "127.0.0.1"
  "event_source" => "site"
  "data" => [
    "keywords" => "New York Hotels"
  ]
]
</source>

The payload is an associative array and in this case you can find the search data in the "data" key. There's other useful event-related information that can be used inside the listener. The following is a list of public methods that you can use for the $event object inside all of your listeners:

* $event->getName()
* $event->getPayload()
* $event->getData()
* $event->getEventUserId()
* $event->getEventUserId()
* $event->getEventIpAddress()

Depending on the event, you can also use additional public methods to retrieve the listing, review, etc. related to that specific event. You can use the existing listener files in the JReviews core as reference when creating your own listeners.


'''Joomla'''

<pre>/components/com_jreviews/jreviews/events/listeners</pre>
<pre>/components/com_jreviews/jreviews/cms_compat/joomla/events/listeners</pre>

'''WordPress'''

<pre>/wp-content/plulgins/jreviews/jreviews/events/listeners</pre>
<pre>/wp-content/plulgins/jreviews/jreviews/cms_compat/wordpress/events/listeners</pre>

= Available Core Events =

== Wildcard ==

The wildcard event allows you to listen to any fired event. You can use the "*" event name in your listener provider. Like this:

<source lang="php">
class CustomListenerProvider extends ListenerProvider
{
	protected $listen = [
		'*' => [
			'JReviews\Listeners\CustomListener'
		],
	];
}
</source>

Then, inside your listener, you can check for specific events being fired using the $event->getName() method. This event is useful for debugging purposes or if you want to execute the same code for multiple events. You can check the event name and only execute the code if it matches one of the desired events.

== Listings ==

* JReviews\Events\ListingWasCreated
* JReviews\Events\ListingWasUpdated
* JReviews\Events\ListingWasFirstPublished
* JReviews\Events\ListingWasDeleted
* JReviews\Events\ListingWasAddedToFavorites
* JReviews\Events\ListingWasRemovedFromFavorites
* JReviews\Events\ListingWasFeatured
* JReviews\Events\ListingWasUnfeatured
* JReviews\Events\ListingWasHeldInModeration
* JReviews\Events\ListingWasAcceptedInModeration
* JReviews\Events\ListingWasRejectedInModeration
* JReviews\Events\ListingInquiryWasCreated
* JReviews\Events\ClaimWasCreated
* JReviews\Events\ClaimWasAcceptedInModeration
* JReviews\Events\ClaimWasHeldInModeration
* JReviews\Events\ClaimWasRejectedInModeration

== Reviews ==

* JReviews\Events\ReviewWasCreated
* JReviews\Events\ReviewWasUpdated
* JReviews\Events\ReviewWasFirstPublished
* JReviews\Events\ReviewWasDeleted
* JReviews\Events\ReviewWasUpvoted
* JReviews\Events\ReviewWasDownvoted
* JReviews\Events\ReviewWasHeldInModeration
* JReviews\Events\ReviewWasAcceptedInModeration
* JReviews\Events\ReviewWasRejectedInModeration

== Owner Replies to Reviews ==

* JReviews\Events\OwnerReplyWasCreated
* JReviews\Events\OwnerReplyWasUpdated
* JReviews\Events\OwnerReplyWasFirstPublished
* JReviews\Events\OwnerReplyWasDeleted
* JReviews\Events\OwnerReplyWasHeldInModeration
* JReviews\Events\OwnerReplyWasAcceptedInModeration
* JReviews\Events\OwnerReplyWasRejectedInModeration

== Review Discussions (Comments) ==

* JReviews\Events\ReviewDiscussionWasCreated
* JReviews\Events\ReviewDiscussionWasUpdated
* JReviews\Events\ReviewDiscussionWasFirstPublished
* JReviews\Events\ReviewDiscussionWasDeleted
* JReviews\Events\ReviewDiscussionWasHeldInModeration
* JReviews\Events\ReviewDiscussionWasAcceptedInModeration
* JReviews\Events\ReviewDiscussionWasRejectedInModeration

== Media ==

* JReviews\Events\MediaWasUploaded
* JReviews\Events\MediaWasFirstPublished
* JReviews\Events\MediaWasDeleted
* JReviews\Events\MediaWasUpdated
* JReviews\Events\MediaEncodingWasCompleted
* JReviews\Events\MediaWasLiked
* JReviews\Events\MediaWasDisliked
* JReviews\Events\MediaWasHeldInModeration
* JReviews\Events\MediaWasAcceptedInModeration
* JReviews\Events\MediaWasRejectedInModeration
* JReviews\Events\ListingMediaWasUploaded
* JReviews\Events\ReviewMediaWasUploaded
* JReviews\Events\ListingPhotoWasFirstPublished
* JReviews\Events\ListingVideoWasFirstPublished
* JReviews\Events\ListingAttachmentWasFirstPublished
* JReviews\Events\ListingAudioWasFirstPublished
* JReviews\Events\ReviewPhotoWasFirstPublished
* JReviews\Events\ReviewVideoWasFirstPublished
* JReviews\Events\ReviewAttachmentWasFirstPublished
* JReviews\Events\ReviewAudioWasFirstPublished

== Reports ==

* JReviews\Events\ReviewWasReported
* JReviews\Events\ReviewDiscussionWasReported
* JReviews\Events\MediaWasReported

== Search ==

* JReviews\Events\ListingSearchWasPerformed
* JReviews\Events\ReviewSearchWasPerformed

= Available Add-on Events =

== ListingResources ==

* JReviews\Events\ListingResourceWasCreated
* JReviews\Events\ListingResourceWasUpdated