16. Programming Plug Ins

Plug-Ins

Advanced programmers have the possibility to create plug-ins. These are code fragments in the form of event listeners which are executed before or after certain actions in the application. By this, you can implement little programs which influence the application logic, such as adding additional factors to the ticket sales computation or trainings.

Register Plug-Ins

Custom event listeners can be registered at any module.xml like as follows:

<plugins>
  <eventlistener event="PlayerTrainedEvent" class="TestPlugin" method="onPlayerTrained" />
</plugins>

The attributes of the element eventlistener are:

• event: Class name of the event. Must match the name of an existing class at /classes/events.
• class: Name of your own class which contains the method defined at method. The class name should end with "Plugin" and placed at folder /classes/plugins.
• method: Name of the function of the class that has been defined at class. This is the function which will contain the plug-in code.

Implementing a Plug-In

Your plug-in basically consists of a function with an object of type Event as argument. You can implement multiple plug-ins in the same class.

Requirements of the plug-in class:

• The name must end with Plugin. Example: PremiumUserPlugin
• The class file must be located at folder /classes/plugins.
• For every registered event listener, there must be a static function handling the event.

A sample implementation of the above registered event listener could look like that:

class TestPlugin {

	public static function onPlayerTrained(PlayerTrainedEvent $event) {
		// your code goes here...
		if ($event->websoccer->getConfig("some_config_parameter")) {
			$event->effectSatisfaction++;
		}
	}
}

Existing events

This is a list of all possible events contained in the standard software.

• UserRegisteredEvent: A new user registered. Either via a registration form or automated registration (for instance due to a custom log-in method).
• PlayerTrainedEvent: A training unit has been computed and the effects will be stored right after the event call. The attribute values will be passed by reference and hence can be changed.
• TicketsComputedEvent: Ticket sales has been computed. Plug-in can influence the revenue since attributes are passed by reference.
• YouthPlayerScoutedEvent: A youth player has been successfully created on scouting.
• YouthPlayerPlayedEvent: A youth player has played at a youth match. Effect on skill can be influenced.
• MatchCompletedEvent: A match (no matter if regular, friendly or youth match) has been simulated. The type of match can be checked via $event->match->type, which can have one of the following values: Ligaspiel (league), Pokalspiel (cup), Freundschaft (friendly), Youth.
• SeasonOfTeamCompletedEvent: A season has ended.

Create custom events

You can also introduce new events in your module and provide them to the community.

Step 1:

Create a new class for your event. Requirements:

• the name must end with Event.
• it must be located at /classes/events.
• it must extend the class AbstractEvent.

Sample implementation:

class MyOwnEvent extends AbstractEvent {
	public $myAttribute;
	
	function __construct(WebSoccer $websoccer, DbConnection $db, I18n $i18n,
			$myAttribute) {
		parent::__construct($websoccer, $db, $i18n);
		
		$this->myAttribute = $myAttribute;
	}

}

Step 2:

Call registered plug-ins via a "Mediator".

Example call:

$event = new MyOwnEvent($this->_websoccer, $this->_db, $this->_i18n,
					"my dummy attribute value");
PluginMediator::dispatchEvent($event);