Templates

Import Data Objects

In the template PHPDocs, list required Data Objects after the Import:. The compiler will allow only imports that belong to the \Data\ namespace.

<?php
/**
 * Import:
 * @var Lightna\Magento\Backend\Data\Product $product
 * @var Lightna\Magento\Backend\Data\Currency $currency
 */

Import Data Objects with Lazy Initialization

If multiple imports are needed, consider implementing a single Data Object that contains other required Data Objects as properties. This ensures all dependencies are loaded with lazy initialization.

Escaping

<?php ...
/**
 * Import:
 * @var Lightna\Magento\Backend\Data\Product $product
 * @var Lightna\Magento\Backend\Data\Currency $currency
 */
?> 
<?php if ($product->price->discount > 0): ?>
    <?php if ($product->price->regular < 100): ?>
        <span class="price-discount percent">
            <span class="value"><?= $product->price->discountPercent() ?></span>
            <?= phrase('off') ?>
        </span>
    <?php else: ?>
        <span class="price-discount amount"><?= $currency->render($product->price->discount) ?></span>
    <?php endif; ?>
<?php endif; ?>

price->discount	Accesses the raw value for use in expressions.
price->discountPercent()	Invoking a property escapes the value. By default, it uses the html method, but you can explicitly specify one of the following: html, json-js, json-js-pretty, json-html, url-param. Custom escape methods can be added by extending Lightna\Engine\App\Escaper::escapeValue.
escape($value)	If a value can't be invoked as a property, use the global escape function.

Translate Phrases

phrase('Default Phrase')	Translates the phrase to the current locale and escapes it using the html method.
_phrase('Default Phrase')	Translates the phrase to the current locale without escaping.

Render Block Attributes

<?php
/**
 * Import:
 * @var Lightna\Engine\Data\Block $block
 */
?>
<div <?= $block->attributes() ?>>
    <?= block() ?>
</div>

Render All Children Blocks

<div class="my-container">
    <?= block() ?>
</div>

Render Specific Children Blocks

<div>
    <?php if ($isLoggedIn): ?>
        <?= block('customer') ?>
    <?php else: ?>
        <?= block('guest') ?>
    <?php endif; ?>
</div>

Custom Rendering of Children Blocks

To access children and their properties in a parent block, use $block->{'.'}. The example below renders children as tabs:

<?php
/**
 * Import:
 * @var Lightna\Engine\Data\Block $block
 */
$tabs = $block->{'.'};
?>
<div class="tabs">
    <?php foreach ($tabs as $name => $tab): ?>
        <div class="<?= $tab->active ? 'active' : '' ?>">
            <?= phrase($tab->title) ?>
        </div>
    <?php endforeach; ?>
    <?php foreach ($tabs as $name => $tab): ?>
        <div class="<?= $tab->active ? 'active' : '' ?>">
            <?= block($name) ?>
        </div>
    <?php endforeach; ?>
</div>

Recursive Block Rendering

If a block needs to call itself, such as for tree rendering, use self as the block name.

<?php
/**
 * Import:
 * @var Lightna\Magento\Backend\Data\Content\Page\Menu\Item $item
 */
?>
<?php foreach ($item->children as $child) { ?>
    <?= block('self', ['item' => $child]) ?>
<?php } ?>

Overriding Imports

In the example above, the item import is overridden by passing it as an argument.

Asset URL

<?php
/**
 * Import:
 * @var Lightna\Engine\Data\Url $url
 */
?>
<img alt="Alt Text"
     src="<?= $url->asset('vendor/module/image/my-image.webp') ?>"/>

The asset() method escapes the value by default. Use asset($url, false) to get an unescaped URL.

Call Template Externally

Use the id defined in the layout, starting with #.

<?= block('#block-id') ?>

For correct functionality on entity pages, entity->type and entity->id must be determined and set for Lightna\Engine\App\Context.

IDE vs AllowDynamicProperties

Not all IDEs fully support the AllowDynamicProperties attribute yet. While it's recommended to define all properties in Data Objects, if undefined properties are used and the IDE raises warnings, you can append &stdClass to the Data Object import to suppress them:

<?php
/**
 * Import:
 * @var Vendor\Module\Data\DataObject&stdClass $data
 */

Overriding Template in Layout

.path.to.existing.block:
  template: vendor/module/my-template.phtml

Overriding Template Using override Folder

See details on the Module Structure page.