Developer Documentation¶
Create a new Element¶
To add a new Element you need to create a new module. A guide can be found in the Magento DevDocs: https://devdocs.magento.com/videos/fundamentals/create-a-new-module/
Tip
You can download our example module to see how it works. Get it from here: Example Module
Step 1: Add the Configuration file¶
After that, an XML configuration file needs to be added in the etc
Directory. The configuration holds the elements
and categories which can be selected in the Element Library. Create a file named lnx_sitebuilder.xml
:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 | <?xml version="1.0" ?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="urn:magento:module:Leonex_SiteBuilder:etc/lnx_sitebuilder.xsd">
<category code="example">
<name>Example Category</name>
</category>
<element code="example_basic"
template="Leonex_SiteBuilderExample::element/example_basic.phtml"
class="Leonex\SiteBuilderExample\ViewModel\ComplexElement"
position="1"
hidden="false"
enabled="true">
<name translate="true">Complex Example</name>
<image>Leonex_SiteBuilderExample::images/complex_example.jpeg</image>
<description translate="true">A complex example of an Site Builder element</description>
<css_class>a-default-css-class</css_class>
<category code="example" />
<fields>
<text code="example_input">
<label translate="true">Example Text</label>
</text>
</fields>
<margin>
<breakpoint code="xs">
<top>1</top>
<bottom>2</bottom>
<left>3</left>
<right>4</right>
</breakpoint>
</margin>
<padding>
<breakpoint code="xs">
<top>5</top>
<bottom>4</bottom>
<left>3</left>
<right>2</right>
</breakpoint>
</padding>
<visible>
<breakpoint code="xs">false</breakpoint>
</visible>
</element>
</config>
|
Name | Value Type | Default Value | Required | Description |
---|---|---|---|---|
code | String | No Default Value | Yes | Element Code, needs to be unique. |
template | String | No Default Value | Yes | Template of the element, e.g.: Namespace_Modle::element/code.phtml |
class | String / Php Class | Leonex\SiteBuilder\ViewModel\Element |
No | Adds a custom Php ViewModel for this element. The Php Class must conform to the Leonex\SiteBuilder\Api\ViewModel\ElementInterface |
position | Integer | MAX_INT | No | Position of the element inside the Element Library |
hidden | Boolean (“true” or “false”) | false | No | If set to false the element will not show up in the Element Library. But it still can be used in a Container Field |
enabled | Boolean (“true” or “false”) | true | No | Enables or Disables the element for the current element |
Name | Required | Description |
---|---|---|
name | Yes | The Name of the element |
image | No | An image file reference. If no image tag is present, the element initials will be displayed |
description | No | Description text |
css_class | No | An additional CSS class. The CSS class can be changed in the Element Configuration |
category | No | category code in which the should be shown in the Element Library. You can add custom categories as shown in the above example |
fields | No | A field holds a value or values which can be changed, e.g. the text of the headline would be a field. For more details on the field configuration please consult the Field Type Reference |
margin | No | An element can provide default margins per breakpoint. These values can be changed in a concrete element in the Element Preview. Per position (top, bottom, left & right) and breakpoint (xs, sm, md & lg) you can provide a spacing level between one and five. |
padding | No | An element can provide default padding per breakpoint. These values can be changed in a concrete element in the Element Preview. Per position (top, bottom, left & right) and breakpoint (xs, sm, md & lg) you can provide a spacing level between one and five. |
visible | No | An element can provide default visibilities per breakpoint. These values can be changed in a concrete element in the Element Preview |
Step 2: Create the Template¶
After the element configuration is finished all that is left to create a corresponding template, that gets rendered when the element is displayed on the frontend. Create a template with the name and path that matches your configuration.
1 2 3 4 5 6 7 | <?php /** @var $block \Leonex\SiteBuilder\Block\Element */ ?>
<?php
$viewModel = $block->getViewModel();
?>
<div class="<?= $block->escapeHtmlAttr($viewModel->getCssClass()); ?>">
<?= $block->escapeHtml($viewModel->getField('example_input')); ?>
</div>
|
As you can see you the template is pretty close to the Magento standard. You can access the ViewModel
from the
block via the getViewModel()
method. With the ViewModel, you have access to all your field data which you can access
via getField(string $code)
method.
The getCssClass()
method renders all the need CSS classes so that the margin, padding and visibility properties work.
So you should always call this method on the outermost HTML container.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 | <?php
namespace Leonex\SiteBuilder\Api\ViewModel;
use Leonex\SiteBuilder\Helper\Config;
interface ElementInterface extends AbstractContentInterface
{
/**
* is_active property in the json
*/
const IS_ACTIVE = 'isActive';
/**
* code property in the json
*/
const CODE = 'code';
/**
* name property in the json
*/
const NAME = 'name';
/**
* css_class property in the json
*/
const ADDITIONAL_CSS_CLASS = 'cssClass';
/**
* margin property in the json
*/
const MARGIN = 'margin';
/**
* padding property in the json
*/
const PADDING = 'padding';
/**
* @return bool
*/
public function isActive(): bool;
/**
* @return string
*/
public function getCode(): string;
/**
* @return string
*/
public function getName(): string;
/**
* @return null|string
*/
public function getAdditionalCssClass(): ?string;
/**
* @param string $breakpoint
* @param string $position
*
* @return int|null
*/
public function getMargin(string $breakpoint, string $position): ?int;
/**
* @param string $breakpoint
* @param string $position
*
* @return int|null
*/
public function getPadding(string $breakpoint, string $position): ?int;
/**
* @param string $breakPoint
*
* @return bool
*/
public function isVisible(string $breakPoint): bool;
/**
* @return ElementTemplateInterface
*/
public function getElementTemplate(): ElementTemplateInterface;
/**
* @return FieldInterface[]
*/
public function getFields(): array;
/**
* @param string $code
*
* @return FieldInterface|null
*/
public function getField(string $code): ?FieldInterface;
/**
* @return Config
*/
public function getConfigHelper(): Config;
}
|
Change an existing element¶
Sometimes you need to change an existing element, which is not in your config file. For instance, the elements that come
with this module. With the referenceElement
-Tag, you can achieve this. Below you can see an example:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 | <?xml version="1.0" ?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="urn:magento:module:Leonex_SiteBuilder:etc/lnx_sitebuilder.xsd">
<referenceElement code="example_basic">
<name translate="true">Updated Example Basic</name>
<fields>
<text code="added_input">
<label translate="true">Added Input</label>
</text>
</fields>
<referenceFields>
<text code="example_input" position="1">
<notice>Added a notice to an existing field</notice>
</text>
</referenceFields>
<visible>
<breakpoint code="xs">false</breakpoint>
<breakpoint code="sm">true</breakpoint>
</visible>
</referenceElement>
</config>
|
In the example an existing element “example_basic” is referenced. In the referenced element you can override all settings
from the original element. One important exception is fields
-tag. With a fields
-tag in a referenceElement
-tag,
you actually add a new field to the element. If you want to change an existing field you should use the `referenceField
-tag.
Adopt Site Builder to your theme¶
Most of the elements should look good in any theme. Sadly we can not guarantee that, so we made it easy to adopt all templates to your theme. Since the module uses the standard Magento template logic all templates can be overridden via theme inheritance. More details on this can be found on the Magento dev docs: https://devdocs.magento.com/guides/v2.3/frontend-dev-guide/themes/theme-inherit.html#theme-inherit-templates
If you have elements that are not relevant can always choose to disable these. Details on how to change an element can be found here: Change an existing element