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>
Element Attribute Information
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
Element Tag Information
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