Modal ViewModel API Reference
The PHP Modal view model uses a fluent interface to configure the dialog.
/** @var \Hyva\Theme\ViewModel\Modal $modalViewModel */
$modal = $modalViewModel->createModal()
->withTemplate('My_Module::dialog-content.phtml')
->overlayDisabled()
->positionBottom()
->addDialogClass('pb-10')
->initiallyVisible();
Be sure to type hint the $modalViewModel so your IDE support you with auto-completion for the available method names.
Methods to configure a modal dialog
The following methods are available to configure a modal through the PHP view model:
overlayEnabled()
Display a backdrop and disable scrolling while the modal is visible. This is the default.
overlayDisabled()
Do not show a backdrop and allow page scrolling while the modal is visible.
initiallyHidden()
Initially hide the modal dialog until show is called.This is the default.
initiallyVisible()
The modal dialog is visible immediately when the page loads.
withOverlayClasses(string ...$classes)
Replace the overlay div element CSS classes with the given ones.
The default overlay classes are:
addOverlayClass(string $class, string ...$moreClasses)
Add the given CSS classes to the overlay div element.
removeOverlayClass(string $class, string ...$moreClasses)
Remove the given CSS classes from the overlay div element.
withContainerTemplate(string $template)
Replace the template for the modal dialog container.The default value is Hyva_Theme::modal/modal-container.phtml
withContainerClasses(string ...$classes)
Replace the container div element CSS classes with the given ones.
The default container classes are:
The container is only used to allow positioning the modal and probably should not need to be customized.
addContainerClass(string $class, string ...$moreClasses)
Add the given CSS classes to the container div element.
The container is only used to allow positioning the modal and probably should not need to be customized.
removeContainerClass(string $class, string ...$moreClasses)
Remove the given CSS classes from the container div element.
The container is only used to allow positioning the modal and probably should not need to be customized.
positionTop()
Position the modal dialog at the center-top side of the window.
positionRight()
Position the modal dialog at center of the right window side.
positionBottom()
Position the modal dialog at center of the bottom window side.
positionLeft()
Position the modal dialog at center of the left window side.
positionCenter()
Position the modal in the center of the window.
This is the default.
positionTopLeft()
Position the modal dialog in the top left corner of the window.
positionTopRight()
Position the modal dialog in the top right corner of the window.
positionBottomRight()
Position the modal dialog in the bottom right corner of the window.
positionBottomLeft()
Position the modal dialog in the bottom left corner of the window.
withDialogRefName(string $refName)
Set the modal dialog Alpine.js x-ref name. When using the PHP Modal view model, the ref name is set automatically. You probably will not need to call this method ever.
getDialogRefName()
Return the modal dialog Alpine.js x-ref name. With multiple modals in one Alpine.js view model, this can be useful for custom triggers to display a specific dialog.
Example
<div x-on:private-content-loaded.window="show('<?= $customerModal->getDialogRefName() ?>', 'my-trigger')">
withDialogClasses(string ...$classes)
Replace the dialog div element CSS classes with the given ones.
The default dialog classes are:
addDialogClass(string $class, string ...$moreClasses)
Add the given CSS classes to the dialog div element.
removeDialogClass(string $class, string ...$moreClasses)
Remove the given CSS classes from the dialog div element.
withAriaLabel(string $label)
Set the modal dialog label for screen reader devices.
Using this option or withAriaLabelledby (below) is important for accessibility.
withAriaLabelledby(string $elementId)
Set element ID containing the label of the modal dialog. The label is used by screen reader devices.
Using this option or withAriaLabel (above) is important for accessibility.
withTemplate(string $template)
Set the template to render as the modal content.
There is no default template.
Example
$modal = $modalViewModel->createModal()->withTemplate('My_Module::my-dialog-content.phtml');
?>
<div x-data="hyva.modal()">
<button @click="<?= $escaper->escapeHtmlAttr($modal->getShowJs()) ?>" type="button" class="btn mt-40" aria-haspopup="dialog">
<?= $escaper->escapeHtml(__('Show Modal')) ?>
</button>
<?= $modal->withAriaLabel('Example modal with content template') ?>
</div>
withBlockName(string $blockName)
If the modal content already has been declared as a block in layout XML, the block name-in-layout can be set using
withBlockName on the modal.
The block will be rendered as the dialog content.
Example
<?php $modal = $modalViewModel->createModal()->withBlockName('my-block') ?>
<div x-data="hyva.modal()">
<button @click="<?= $escaper->escapeHtmlAttr($modal->getShowJs()) ?>" type="button" class="btn mt-40" aria-haspopup="dialog">
<?= $escaper->escapeHtml(__('Show Modal')) ?>
</button>
<?= $modal->withAriaLabel('Example modal with content from predeclared block') ?>
</div>
withContent(string $content)
The given string $content will be rendered as the modal dialog content.
Example
<div x-data="hyva.modal()">
<button @click="show" type="button" class="btn mt-40" aria-haspopup="dialog"><?= $escaper->escapeHtml(__('Show')) ?></button>
<?= $modalViewModel->createModal()->withContent(<<<END_OF_CONTENT
<div id="the-label">{$escaper->escapeHtml(__('Inline Content Example'))}</div>
<div class="mt-20 flex justify-between gap-2">
<button @click="hide" type="button" class="btn">
{$escaper->escapeHtml(__('Cancel'))}
</button>
<button x-focus-first @click="doSomething" type="button" class="btn btn-primary">
{$escaper->escapeHtml(__('Heck Yes!'))}
</button>
</div>
END_OF_CONTENT
)->withAriaLabelledby('the-label') ?>
</div>
HEREDOC expressions incompatible with Magento built in HTML minification
The regular expression used by Magento to parse PHP while minifying output has a bug.
It expects the closing heredoc delimiter to be followed by a semicolon, even though it is not required by PHP, and in fact can't be used when the heredoc is used as an expression like in the example above.
We recommend disabling minification, but if that is not an option, you need to use the heredoc as a statement instead, that is, assign the string to a variable.
The following code breaks Magento minification but is valid PHP:
$content = <<<HEREDOC
<div>My Content</div>
HEREDOC
$modalViewModel->createModal()->withContent($content);
The following code works with Magento minification but causes a syntax error to be raised, because it is invalid PHP:
The following code works with Magento minification and is also valid PHP:
getContentRenderer()
(This method is available since Hyvä release 1.1.9)
If a modal is rendered with a template, it can be useful to pass values to the block rendering it.
This is possible with the getContentRenderer() method.
The method returns the Template block instance that is used to render the modal template.
Values can be passed to the template using the standard block methods setData() or assign().
Example:
$modal = $modalViewModel->createModal()->withTemplate('My_Module::foo.phtml');
$modalBlock = $modal->getContentRenderer();
$modalBlock->assign('foo', $foo);
$modalBlock->setData('bar', $bar);
// then in foo.phtml $foo is automatically set and $block->getData('bar') will return $bar
?>
<?= /* Be sure to render $modal, not $modalBlock */ $modal ?>