Element

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.

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;
    }
}