Element request handler

Purpose #

An ElementRequestHandler is needed if a custom Element needs to process requests originating from that Element like form POSTs or GET requests.

In contrast to a RequestHandler this interface is only for Elements and is needed if the handler reacts on events from your element. For a request to be send to the ElementRequestHandler, the POST param elemID with the ID of the element from the getId() function is needed.

/**
 * A request handler that handles a part or the full Request for Elements.
 */
interface ElementRequestHandler {
	
	/**
	 * The method a request is passed to for the Element.
	 * @param Request $request The Request object encapsulation all needed fields and abstracting the super globals away
	 * @return Response The Response object encapsulating the response
	 */
	public function processRequestForElement(Request &$request):?Response;
}

Example #

<?php
declare(strict_types=1);

namespace Iacbox\Loginpage\Extension\ExampleElement;

use Iacbox\Loginpage\Extension\ElementExtension;
use Iacbox\Loginpage\Router\ElementRequestHandler;
use Iacbox\Loginpage\Request;
use Iacbox\Loginpage\Session;
use Iacbox\Loginpage\Response;
use Iacbox\Loginpage\Html\HtmlBuilder;
use \DOMElement;

class ExampleElementExtension extends ElementExtension implements ElementRequestHandler{
	// prepare DOMElement representing the element with a form send to ElementRequestHandler
	public function prepareRender(Request &$request, HtmlBuilder $builder):DOMElement {
		// get RenderHelper
		$renderHelper = $this->getRenderHelper();
		// create base DOMElement 
		$div = $builder->createDiv(['lp-element']);
		$builder->setID($div, $this->id);
		// add form for ElementRequestHandler as Xhr (automatically adds required post param for ElementRequestHandler)
		$form = $this->createElementForm($builder, '/' , true, true);
		// add additional fields to form
		// ...

		// add submit button
		$renderHelper->addSubmit($request, $builder, $form, 'submit-element', 'Submit', 'submit');
		$div->appendChild($form);
		return $div;
	}

	// process request for element (added with ElementRequestHandler)
	public function processRequestForElement(Request &$request):?Response {
		// check if correct submit button is used
		if ($request->getPostParam('submit-element') != null) {
			// do something with data from form
			//...

			// generate success message to replace content of element
			// get RenderHelper
			$renderHelper = $this->getRenderHelper();
			$builder = $renderHelper->getHtmlBuilder();
			// create div with success message
			$successDiv = $builder->createDiv(['lp-element']);
			$builder->setID($successDiv, $this->id);
			$renderHelper->addText($request, $builder, $successDiv, 'Success', null, 'center');
			// generate HTML from DOMElement
			$partialHtml = $renderHelper->createHtmlFromDOMElement($builder, $successDiv);
			// send partial HTML to replace content of element
			$responseData = [
				'parentID' => $this->id,
				'html' => $partialHtml,
			];
			return Response::createJSONResponse($responseData);
		}
		// no response if not from form 
		return null;
	}
}