Configuration
Purpose
An extension might needs configuration values that can’t be hard-coded into the extension itself because
- these values are different per location (IDs, …)
- these values are credentials and should not be stored in the code
- these values are subject to change (like API endpoint URLs)
By implementing the ConfigurableLpExtension interface an extension gets a config section in the page tab at the bottom as soon as the extension is activated for this login page.
Configuration can be added to any extension, no matter if this extension has a visual representation or is just a handler.
Interface reference
/**
* Adds configuration to an extension
*/
interface ConfigurableLpExtension extends LoginpageExtension {
/**
* Implement this method to return hash representing the configuration of the expension
* @api
* @param string $loginpageID ID of the loginpage requesting the configuration
* @param string|null $pageID ID of the page in the loginpage requesting the configuration
* @return array Hash representing the configuration
*/
public function getLpEditorConfig(string $loginpageID, ?string $pageID = null):array;
}
Config data structure
Types
| Type | Description |
|---|---|
input | A text input field for single line text |
textarea | A textarea input field for multi-line texts |
checkbox | A checkbox for boolean values. No value evaluates to false |
select | A select input to choose one out of many values |
Properties
Overview of possible properties that can be set for the different input types.
| Applicable on type | Property | Mandatory | Default | Description |
|---|---|---|---|---|
| All types | label | Yes | empty | Label text |
| All types | defaultValue | No | empty | Set a default value for this field which gets prefilled/preselected |
| All types | optional | No | true | true|false Set to false if this property needs to be set |
input, textarea | validate | No | true | Validate different input formats |
input, textarea | validate_regex | No | true | If validate is regex add this property to specify the regular expression |
input, textarea | placeholder | No | empty | Text set as placeholder attribute of this input field |
select | options | Yes (select) | - | Key/value hashmap [ "value1" => "Display name 1", "value2" => "Display name 2" ] |
Validation
Optionally a validation can be added to any configuration field using the validate field.
| Type | Description |
|---|---|
numeric | Input has to be a number |
email | Weak email format check. This check is not too strict as some exotic addresses won’t work otherwise. |
url | Check for a valid URL representation |
regex | Do a validation based on regular expressions. An additional field validate_regex is needed which contains the expression |
Example
<?php
namespace Iacbox\Loginpage\Extension\MyCustom;
class MyCustomExtension implements ConfigurableLpExtension {
public function getLpEditorConfig(string $loginpageID, ?string $pageID = null):array {
return [
'api-endpoint' => [
// type is mandatory: text, checkbox, select
'type' => 'input',
'label' => 'API Endpoint',
'optional' => false,
'defaultValue' => 'https://api.myservice.com/v2'
],
'api-token' => [
// type is mandatory: text, checkbox, select
'type' => 'input',
'label' => 'API Token',
'optional' => false,
'placeholder' => 'Format: 4bfa6a01-2405-946a-6a0d-0085d1bef5e1'
],
];
}
}
Get Configuration in Extension
Each extension parent class provides a getPageConfig function to get the configuration set in the loginpage editor
Example
// read Config from above example
public function myFunction() {
// get Page config
$config = $this->getPageConfig();
$apiEndpoint = $config['api-endpoint'];
$apiToken = $config['api-token'];
}
Configuration for Elements
ElementExtension stores the config as part of the login page structure as every instance of an element has its own config.
In addition ElementExtension already implements the ConfigurableLpExtension interface.
The definition of the config for elements works the same as for other extensions with getLpEditorConfig function.
But in addition to the config the element requires the implementation of the config of two additional functions serializeCustomSettings and deserializeCustomSettings
Example
<?php
namespace Iacbox\Loginpage\Extension\MyCustomElement;
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 MyCustomElementExtension extends ElementExtension {
// variables to hold settings
protected $title;
protected $showTitle;
// example config with 2 settings 'title' and 'show-title'
public function getLpEditorConfig(string $loginpageID, ?string $pageID = null):array {
return [
'title' => [
// type is mandatory: text, checkbox, select
'type' => 'input',
'label' => 'Title',
'optional' => false,
'defaultValue' => 'My title'
],
'show-title' => [
// type is mandatory: text, checkbox, select
'type' => 'checkbox',
'label' => 'Show title',
'optional' => true,
'defaultValue' => false,
],
];
}
// serialize to save settings from login page editor to element
public function serializeCustomSettings():array {
return [
'title' => $this->title,
'show-title' => $this->showTitle,
];
}
// deserialize to get settings saved to element
public function deserializeCustomSettings(array $objAsMap) {
$this->title = array_key_exists('title', $objAsMap) ? $objAsMap['title'] : '';
$this->showTitle = array_key_exists('show-title', $objAsMap) ? $objAsMap['show-title'] : false;
}
}