WCF 2.1 — EventListener and TemplateListener changes

  • All of the developer spotlights up to now were about features that are visible to the end user. But of course we provided you with new APIs that allow to build plugins that were impossible before, as well.


    IParameterizedEventListener


    As of Community Framework 2.1 the class firing an event can provide an array with additional arguments as the third parameter of fireAction. This allows for more possible event listeners, as one can make the local variables of a method available as well, instead on relying on the class attributes.


    PHP: QuickReplyManager.class.php
    EventHandler::getInstance()->fireAction($this, 'createMessage', $additionalFields);


    Note that the array is passed by reference, make sure that you only provide variables and not the array itself!


    Every event listener implementing the \wcf\system\event\listener\IParameterizedEventListener will be passed the array by reference as the 4th parameter of execute():


    PHP: PreParserAtUserListener.class.php
    class PreParserAtUserListener implements IParameterizedEventListener {
    /**
    * @see \wcf\system\event\listener\IParameterizedEventListener::execute()
    */
    public function execute($eventObj, $className, $eventName, array &$parameters) {


    If the parameters were modified the modifications are passed to the event listener is executed next. Make use of the nice attribute to ensure a certain ordering.


    The legacy IEventListener interface will be phased out in three steps:


    • WCF 2.1: [list]
    • Deprecation of \wcf\system\event\IEventListener
    • Introduction of \wcf\system\event\listener\IParameterizedEventListener

    [*]WCF 2.2:

    • Removal of \wcf\system\event\IEventListener
    • Introduction of \wcf\system\event\listener\IEventListener (Note the additional \listener in the namespace)
    • Deprecation of \wcf\system\event\listener\IParameterizedEventListener

    [*]WCF 2.3

    • Removal of \wcf\system\event\listener\IParameterizedEventListener

    [/list]The reason for this the unusual placement of the IEventListener interface. Contrary to most other interfaces it resides in the folder above the classes implementing it. Therefore one had to use it or reference it by it's fully qualified class name.


    Therefore every developer is encouraged to update his event listeners to implement IParameterizedEventListeners in his Community Framework 2.1 plugins!


    This feature is not forward compatible: The interface is missing in Community Framework 2.0.


    New and improved Events


    You probably already guessed it: We provided some new events and improved others. You are encouraged to help making the list longer: Tell us about events that you are missing.


    Here's the current list of new events. I am using function call style for the new parameterized event listeners:

    • validateParameters@\wcf\system\message\QuickReplyManager
    • createMessage@\wcf\system\message\QuickReplyManager($additionalFields = array())
    • createdMessage@\wcf\system\message\QuickReplyManager(array('message' => $message))
    • beforeChangeUser@\wcf\system\session\SessionHandler(array('user' => $user, 'hideSession' => $hideSession))
    • afterChangeUser@\wcf\system\session\SessionHandler

    Improved events:

    • finalizeAction@\wcf\data\comment\CommentAction: You can access the newly created comment by $eventObj->createdComment (addComment) and the newly created comment response by $eventObj->createdResponse (addResponse)

    This feature is partly forward compatible: While the plugin technically could be installed it will probably missing an important part of functionality, as Community Framework 2.0 is missing the event.


    Template listeners support <nice>


    A nice new feature is the support of <nice> for template listeners. Analogous to event listeners it allows you to change the execution order of the installed template listeners. Supported values are between -128 and 127 (both inclusive). The default value is zero, template listeners with a lower nice value are executed first.


    This feature is forward compatible: The <nice> tag is ignored in Community Framework 2.0. If you heavily rely on it you should require Community Framework 2.1, though.


    TemplateListenerCacheBuilder


    \wcf\system\cache\builder\TemplateListenerCacheBuilder is now deprecated. You are probably not using it, as it was not needed in Community Framework 2.0.

  • Introducing wcf\system\event\listener\IEventListener would perfectly make sense, but I don't really like the idea of removing \wcf\system\event\IEventListener. This would lead to two interfaces with the same exact name, but different signatures.


    The current state is somewhat okay-ish imho.

    Alexander Ebert
    Senior Developer WoltLab® GmbH