Element
On this page
Purpose
- An Element is an extension that renders HTML and/or Javascript into the login page.
- Every Element shows up in the Login Page Editor and can be added once or multiple times via drag-and-drop.
If a new login method is to be added, please use the special extension type described here.
ElementExtension class
To create a new custom element extend the Iacbox\Loginpage\Extension\ElementExtension
class.
Class reference
/**
* Returns the priority of extension which defaults to LoginpageCallback::PRIO_DEFAULT = 50.
* Override this method to return a higher or lower priority for this extension. This influences the order of executed handlers.
* @return int Priority of Extension (0 = lowest; 100 = highest) - default is 50
*/
public function getPriority():int {}
/**
* Returns name which is used in login page editor
* Override this method to set display name of the element in the login page editor
* @return string Name displayed in editor
*/
public function getDisplayName():string {}
/**
* Runs immediatly after element is loaded
* Override this method to run code immediatly after element is loaded
* @return void
*/
public function onLoaded() {}
/**
* Returns a config hash used to generate the UI config elements in login page editor.
* Override this method if this the element needs custom configuration changeable in login page editor.
* @param string $loginpageID ID of the login page where the element is located
* @param string $pageID ID of the sub page where this element is located
* @return array Config hash used in login page editor
*/
public function getLpEditorConfig(string $loginpageID, ?string $pageID = null):array {}
/**
* Returns true if this Element should be rendered right now.
* Override this method to add conditions if the element should be rendered based config or request.
* @param Request $request Request from login page
* @return bool true if it should be rendered else false
*/
public function shouldRender(Request &$request):bool {}
/**
* Returns a DOMElement representing the HTML of this element
* Override this method to build the partial DOM representing this element.
* The passed HtmlBuilder provides creation methods for most needed HTML elements.
* @param Request $request Request from login page
* @param HtmlBuilder $builder HtmlBuilder from login page
* @return DOMElement DOMElement representing the element
*/
public function prepareRender(Request &$request, HtmlBuilder $builder):DOMElement {}
/**
* Gets called during serializing where custom settings can be added to be persistent.
* Override this method to add custom configs to the element.
* @return array [Key => Value] hash of custom settings
*/
public function serializeCustomSettings():array {}
/**
* Gets called during deserialization when the login page is loaded from disk.
* Override this method to load custom configs of the element
* @param array $objAsMap [Key => Value] hash of serialized settings
* @return void
*/
public function deserializeCustomSettings(array $objAsMap) {
/**
* Returns an instance of RenderHelper
* @return RenderHelper Instance of RenderHelper
*/
public function getRenderHelper():RenderHelper {}
/**
* Adds default element layout settings to login page editor settings
* @param array $settings Array of settings to add layout settings to
* @param bool $addAlignment should alignment setting be added
* @param bool $addPadding Should padding setting be added
* @param bool $addTextStyle Should text style setting be added
* @return void
*/
public function addDefaultSettings(array &$settings, bool $addAlignment, bool $addPadding, bool $addTextStyle) {}
/**
* Returns CSS classes for basic element and layout settings
* @param bool $onlyLayout Returns only layout classes
* @return array Array of CSS classes
*/
public function getElementDefaultCSS(bool $onlyLayout = false):array {}
/**
* Creates a form DOMElement with all required fields to work for elements implementing ElementRequestHandler
* @param HtmlBuilder $builder HtmlBuilder from login page
* @param string $action action used in form
* @param bool $isXhr Submit as XHR
* @param bool $ignoreRender set flag to ignore form for onPrepareRender calls
* @param array $cssClasses Array of additional CSS classes
* @return DOMElement form element created
*/
public function createElementForm(HTMLBuilder $builder, string $action, bool $isXhr, bool $ignoreOnRender, array $cssClasses = []):DOMElement {}
/**
* Returns rendered HTML for this element
* @param Request $request Request from login page
* @return string HTML representing this elements DOMElement from prepareRender
*/
public function renderElement(Request $request):string {}
/**
* Check if code is called in login page editor. Some elements or login methods
* may want to render a fake representation during preview.
* @return bool true if called in login page editor
*/
public function inPreviewMode():bool {}
/**
* Check if code is called in login page.
* @return bool true if called in login page
*/
public function inProductionMode():bool {}
/**
* Logs error for debugging
* @param string $message Message displayed
* @param Throwable $error Php error object for message and stack trace
* @return void
*/
public function logError(string $message, Throwable $error = null) {}
/**
* Logs warning for debugging
* @param string $message Message displayed
* @return void
*/
public function logWarning(string $message) {}
/**
* Logs info for debugging
* @param string $message Message displayed
* @return void
*/
public function logInfo(string $message) {}
// Do not overwrite following methods!
// Required for correct working of extensions in login page
public function __construct() {}
public function getID():string {}
public function getType():string {}
public function jsonSerialize() {}
public function initParentProperties(array $objAsMap) {}
public static function jsonDeserialize(array $objAsMap):object {}
public function init() {}
public function setSlot(Slot &$slot) {}
public function getRouter():Router {}
public function getLoginpage():Loginpage {}
public function getPage():Page {}
public function getSlot():Slot {}
Example
<?php
declare(strict_types=1);
namespace Iacbox\Loginpage\Extension\ExampleElement;
use Iacbox\Loginpage\Extension\ElementExtension;
use Iacbox\Loginpage\Request;
use Iacbox\Loginpage\Session;
use Iacbox\Loginpage\Response;
use Iacbox\Loginpage\Html\HtmlBuilder;
use \DOMElement;
class ExampleElementExtension extends ElementExtension {
// variable to hold message from settings
protected $welcomeMessage;
// set name displayed in login page editor
public function getDisplayName():string {
return 'Welcome';
}
// add input for welcome message to default element layout settings
public function getLpEditorConfig(string $loginpageID, ?string $pageID = null):array {
$settings = [
'welcomeMessage' => [
'type' => 'input',
'label' => 'Welcome message',
'optional' => false,
'translatable' => true,
'defaultValue' => 'Welcome'
],
];
// add default element layout settings
$this->addDefaultSettings($settings, true, true, true);
return $settings;
}
// add new custom settings to deserialize to get settings from editor
public function deserializeCustomSettings(array $objAsMap) {
$this->welcomeMessage = array_key_exists('welcomeMessage', $objAsMap) ? $objAsMap['welcomeMessage'] : '';
}
// add new custom settings to correctly serialize new settings
public function serializeCustomSettings():array {
return [
'welcomeMessage' => $this->welcomeMessage,
];
}
// prepare DOMElement representing the element
public function prepareRender(Request &$request, HtmlBuilder $builder):DOMElement {
// get RenderHelper
$renderHelper = $this->getRenderHelper();
// get CSS classes for default layout settings
$cssClasses = $this->getElementDefaultCSS();
// create base DOMElement
$div = $builder->createDiv($cssClasses);
$builder->setID($div, $this->id);
// add welcome message text
// get translation key and translated text for welcome message
$translationKey = 'welcome';
$translatedText = $renderHelper->translate($translationKey, $this->welcomeMessage);
$renderHelper->addText($request, $builder, $div, $translatedText, $translationKey);
return $div;
}
}