Event handlers

Purpose #

Event handlers are generic extension points which can be added to a base extension to react on certain event.

Events #

PrepareForRenderListener #

Chances are good you want to use a Custom Element. Use this listener only if you don’t need/want the functionality

/**
 * A Listener which is called after DOMElement for slot is prepared but before it is rendered
 */
interface PrepareForRenderListener extends LoginpageCallback {
	
	/**
	 * Implement this method to modify the DOMElement to be rendered
	 * @param Request $request Request object used for the login page
	 * @param HtmlBuilder $builder HtmlBuilder of the login page
	 * @param DOMElement $rootNode DOMElement to be rendered
	 * @return DOMElement DOMElement to be rendered
	 */
	public function onPrepareForRender(Request &$request, HtmlBuilder $builder, DOMElement $rootNode):DOMElement;
}

// example adding an text into each login method before submit part of login method
public function onPrepareForRender(Request &$request, HtmlBuilder $builder, DOMElement $rootNode):DOMElement {
    // get RenderHelper
    $renderHelper = $this->getRenderHelper();
    // get insertPoints for all login methods
    $excludeLoginMethods = [];
    $insertPoints = $renderHelper->getInsertPointsBeforeSubmitOfLoginMethodsWithExcludeList($rootNode, $excludeLoginMethods);
    // loop over each insert point
    foreach ($insertPoints as $insertPoint) {
        // create DOMElement to insert
        $elementToInsert = $builder->createText('Example text to insert');
        // insert new DOMElement 
        $insertPoint['parent']->insertBefore($elementToInsert, $insertPoint['insertPoint']);
    }
    // return $rootNode
    return $rootNode;
}

FormPostEntryListener #

Do something before the form is processed by the default login page logic. You will want this if you want to manipulate a form POST for example. Use this rarely.

/**
 * A Listener which is called before login page logic runs
 */
interface FormPostEntryListener extends LoginpageCallback {
	
	/**
	 * Implement this method to run code before the form is processed by login page logic
	 * @api
	 * @param Request $request Request object used for the login page
     * @return void
	 */
	public function onFormPostEntry(Request &$request);
}

// example modifying POST params before login page logic runs
public function onFormPostEntry(Request &$request) {
    // read POST params
    $postParams = $request->getPostParams();
    // modify POST params
    // ...

    // overwrite POST params of request with modified POST params 
    $request->overwritePostParams($postParams);
}

FormPostLeaveListener #

Probably the most interesting event as it allows you to react on (un)successful logins.

For example: Send the given email address of your guest to a cloud CRM. Or trigger any web-hook of a cloud service after a login.

/**
 * A Listener which is called after login page logic
 */
interface FormPostLeaveListener extends LoginpageCallback {
	
	/**
	 * Implement this method to run code after the form is processed by login page logic
	 * @api
	 * @param Request $request Request object used for the login page
	 * @return void
	 */
	public function onFormPostLeave(Request &$request);
}

// run code if client is online
public function onFormPostLeave(Request &$request) {
    // check if client is online
    if ($request->getSession()->getState() == Session::ONLINE) {
        // run code
        // ...
    }
}