Reference: Events

Starting with Kajona v4.5, the way how events are handled was rewritten from scratch. Events may be used to react on special actions triggered by the system. For example, it's possible to be notified if a record is deleted, if a record is updated or if a user logs into the system for the first time.

All events handled by Kajona are identified using a string-based identifier, e.g. core.system.recordupdated. In order to be notified in case of an event, you have to implement the generic interface GenericeventListenerInterface. Compared to a more type-safe event-interface (e.g. interface_record_deleted_listener", the generic approach reduced the coupling between modules and avoids hard-coded dependencies between packages Example: If your faqs module wants to react on events triggered by the search, the GenericeventListenerInterface is all you have to implement. If the interface was named SearchTriggeredInterface and the interface is provided by the search-package, your faq implementation will fail if the search package is not available (due to an undefined interface).

Handling events

If you want to handle a certain event, you have to provide a listener and register the listener for this event. Let's say you want to be notified in case a record is deleted in order to write a line to a logfile. The listener you have to provide would be the following implementation:

class LoggingRecorddeletedlistener implements GenericeventListenerInterface {
 public function handleEvent($strEventName, array $arrArguments) {     
  list($strSystemid, $strSourceClass) = $arrArguments;
  Logger::getInstance()->addLogRow("record delete, id: ".$strSystemid, Logger::$levelInfo);
  return true;
 }
}
CoreEventdispatcher::getInstance()->removeAndAddListener( "core.system.recorddeleted"​, new LoggingRecorddeletedlistener());

This class takes care of everything. The last lines registeres the listener at the CoreEventdispatcher for the event identified by core.system.recorddeleted. The listener implements the interface and drops a line to the logfile.

Kajona scans the filesystems for possible listener at startup, so you don't have to worry that your handler will be registered. All you have to stick to is placing your listener within the packages system-directory.

Throwing events

Throwing an event is a piece of cake! All you have to know is the identifier of an event. Let's keep to the example above: Let's notify listeners about a deleted record. Normally this event is handled by Kajona, but let's trigger it again:

CoreEventdispatcher::getInstance()->notifyGenericListeners( "core.system.recorddeleted", array($strSystemid, get_class($objRecordDeleted)));

All we do is fetching an instance of the core_eventdispatcher and calling the method notifyGenericListeners. Arguments to this method are the identifier of the event and an array of arguments. This array of arguments will be passed to the registered listeners using the callback-method handleEvent.

Thats all. You should now be able to provide and register event-listeners and to throw new events based on an identifier.

Overview of core events

Identifier Description
core.system.request.startprocessing Since 4.6
Arguments bool $bitAdmin
string $strModule
string $strAction
string $strLanguageParam
Description Invoked right before starting to process the current request. The event is triggered by the request-dispatcher right before the request is given over to the controller.
core.system.request.endprocessing Since 4.6
Arguments bool $bitAdmin
string $strModule
string $strAction
string $strLanguageParam
Description Invoked right before finishing to process the current request. The event is triggered by the request-dispatcher right before closing the session and passing back the response object. You may modify the request by accessing the response-object.
core.system.request.aftercontentsend Since 4.6
Arguments RequestEntrypointEnum $objEntrypoint
Description Invoked right after sending the response back to the browser, but before starting to shut down the request.
This means you are not able to change the response anymore, also the session is already closed to keep other threads from waiting. Use this event to perform internal cleanups if required.
core.system.recordupdated Since 4.5
Arguments \Kajona\System\System\Model $objRecord
bool $bitRecordCreated
Description Thrown whenever a record is updated to the database.
The param $bitRecordCreated indicates if a record was created(true) of if is only being updated(false)
core.system.objectassignmentsupdated Since 4.8
Arguments string[] $arrNewAssignments
string[] $areRemovedAssignments
string[] $areCurrentAssignments
Root $objObject
string $strProperty

return bool
Description Triggered as soon as a property mapping to objects is updated. Therefore the event is triggered as soon as assignments are added or removed from an object. The event gets a list of all three relevant items: assignments added, assignments removed, assignments remaining. The relevant object and the name of the changed property are passed, too.
Return a valid bool value, otherwise the transaction will be rolled back!
core.system.recordcopied Since 4.5
Arguments string $strOldSystemid
string $strNewSystemid
\Kajona\System\System\Model $objNewObjectCopy
Description Called whenever a record was copied. Event will be fired BEFORE child objects are being copied. Useful to perform additional actions, e.g. update / duplicate foreign assignments.
core.system.recordcopyfinished Since 4.6
Arguments string $strOldSystemid
string $strNewSystemid
\Kajona\System\System\Model $objNewObjectCopy
Description Called whenever a record was copied. Event will be fired AFTER child objects were copied. Useful to perform additional actions, e.g. update / duplicate foreign assignments.
core.system.permissionschanged Since 4.5
Arguments string $strSystemid 
array $arrPermissions 
Description Invoked if the permissions of a record have been changed. Triggered only by the "root" node of the change cascade.
core.system.previdchanged Since 4.5
Arguments string $strSystemid 
string $strOldPrevId
string $strNewPrevid
Description Invoked every time a records status was changed. Please note that the event is only triggered on changes, not during a records creation.
core.system.statuschanged Since 4.8
Arguments string $strSystemid
Root $objObject
string $intOldStatus
string $intNewStatus
Description Thrown if a records parent-id changed, e.g. if a record is moved within a hierarchical tree.
core.system.recorddeleted Since 4.5
Arguments string $strSystemid   
string $strSourceClass
Description Thrown as soon as record is deleted from the database. Listen to those events if you want to trigger additional cleanups or delete linked contents.
Make sure to return a matching boolean-value, otherwise the transaction may be rolled back.
core.system.recorddeleted.logically Since 4.8
Arguments string $strSystemid   
string $strSourceClass
Description Thrown as soon as record is deleted logically, so set inactive. The reocord is NOT removed from the database. Listen to those events if you want to trigger additional cleanups or delete linked contents.
Make sure to return a matching boolean-value, otherwise the transaction may be rolled back.
core.system.recordrestored.logically Since 4.8
Arguments string $strSystemid
string $strSourceClass The class-name of the object deleted
\Kajona\System\System\Model $objObject The object which is being restored
Description Called whenever a records is restored from the database.
The event is fired after the record was restored but before the transaction will be committed.
Make sure to return a matching boolean-value, otherwise the transaction may be rolled back.
core.system.userfirstlogin Since 4.5
Arguments string $strUserid
Description Thrown if a users logs into the system for the very first time. May be used to trigger initializations such as creating dashboard widgets or welcome messages.
core.system.userlogin Since 4.5
Arguments string $strUserid
Description Thrown if a users logs into the system. May be used to trigger initializations.
core.system.userlogout Since 4.5
Arguments string $strUserid
Description Thrown if a users logs out of the system. May be used to trigger cleanup actions.
     
core.search.objectindexed Since 4.5
Arguments \Kajona\System\System\Model $objInstance
SearchDocument ​$objSearchDocument
Description Thrown as soon as an object is indexed by the search. Listen to this event if you want to add additional keywords to the objects' search index entry.
core.packagemanager.packageupdated Since 5.1
Arguments @param \Kajona\Packagemanager\System\PackagemanagerPackagemanagerInterface $objManager the installed / updated package
Description Event thrown as soon as a package was either installed or updated.
https://raw.githubusercontent.com/kajona/kajonacms/master/module_system/docs/reference_events.md
No comments made till now
Fork me on GitHub