Table of Contents & Menu
On this page
Navigation

Modal ViewModel API Reference

The PHP Modal ViewModel offers a fluent interface for configuring dialogs.

/** @var \Hyva\Theme\ViewModel\Modal $modalViewModel */
$modal = $modalViewModel->createModal()
    ->withTemplate('My_Module::dialog-content.phtml')
    ->overlayDisabled()
    ->positionBottom()
    ->addDialogClass('pb-10')
    ->initiallyVisible();

Type hint $modalViewModel for IDE auto-completion.

Methods to configure a modal dialog

overlayEnabled()

Displays a backdrop and disables scrolling while the modal is visible. This is the default behavior.

overlayDisabled()

Hides the backdrop and allows page scrolling while the modal is visible.

initiallyHidden()

Hides the modal dialog until show is called. This is the default behavior.

initiallyVisible()

Makes the modal dialog visible immediately upon page load.

withOverlayClasses(string ...$classes)

Replaces the overlay div element's CSS classes with the provided ones.

Default overlay classes:

['fixed', 'inset-0', 'bg-black', 'bg-opacity-50', 'z-10']

addOverlayClass(string $class, string ...$moreClasses)

Adds CSS classes to the overlay div element.

removeOverlayClass(string $class, string ...$moreClasses)

Removes CSS classes from the overlay div element.

withContainerTemplate(string $template)

Replaces the modal dialog container template. Default: Hyva_Theme::modal/modal-container.phtml

withContainerClasses(string ...$classes)

Replaces the container div element's CSS classes with the provided ones.

Default container classes:

['fixed', 'flex', 'justify-center', 'items-center', 'text-left']

Note: The container is primarily for modal positioning and usually doesn't require customization.

addContainerClass(string $class, string ...$moreClasses)

Adds CSS classes to the container div element. Note: The container is primarily for modal positioning and usually doesn't require customization.

removeContainerClass(string $class, string ...$moreClasses)

Removes CSS classes from the container div element. Note: The container is primarily for modal positioning and usually doesn't require customization.

positionTop()

Positions the modal dialog at the center-top of the window.

positionRight()

Positions the modal dialog at the center of the right window side.

positionBottom()

Positions the modal dialog at the center of the bottom window side.

positionLeft()

Positions the modal dialog at the center of the left window side.

positionCenter()

Positions the modal in the center of the window. This is the default.

positionTopLeft()

Positions the modal dialog in the top-left corner of the window.

positionTopRight()

Positions the modal dialog in the top-right corner of the window.

positionBottomRight()

Positions the modal dialog in the bottom-right corner of the window.

positionBottomLeft()

Positions the modal dialog in the bottom-left corner of the window.

positionNone()

*(Since Hyvä 1.3.10)* Disables automatic modal positioning, requiring manual positioning using addContainerClass or withContainerClasses.

withDialogRefName(string $refName)

Sets the modal dialog's Alpine.js x-ref name. This is usually set automatically by the ViewModel, so you rarely need to call it.

getDialogRefName()

Returns the modal dialog's Alpine.js x-ref name. Useful for custom triggers to display specific dialogs when multiple modals are in one Alpine.js ViewModel.

Example

<div x-on:private-content-loaded.window="show('<?= $customerModal->getDialogRefName() ?>', 'my-trigger')">

withDialogClasses(string ...$classes)

Replaces the dialog div element's CSS classes with the provided ones.

Default dialog classes:

['inline-block', 'bg-white', 'shadow-xl', 'rounded-lg', 'p-10']

addDialogClass(string $class, string ...$moreClasses)

Adds CSS classes to the dialog div element.

removeDialogClass(string $class, string ...$moreClasses)

Removes CSS classes from the dialog div element.

withAriaLabel(string $label)

Sets an ARIA label for the modal dialog, improving accessibility for screen readers. Use this or withAriaLabelledby.

withAriaLabelledby(string $elementId)

Sets the ID of an element that labels the modal dialog, improving accessibility for screen readers. Use this or withAriaLabel.

withTemplate(string $template)

Sets the PHTML template to render as the modal's content. 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)

Renders content from an existing layout XML block. Set the block's name-in-layout.

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)

Renders the provided string $content directly as the modal dialog's 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!'))}
</div>
</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: 

$modalViewModel->createModal()->withContent(<<<HEREDOC
<div>My Content</div>
HEREDOC;
);

The following code works with Magento minification and is also valid PHP: 

$content = <<<HEREDOC
<div>My Content</div>
HEREDOC;
$modalViewModel->createModal()->withContent($content);

getContentRenderer()

*(Since Hyvä 1.1.9)* Returns the Template block instance used to render the modal's content template. This allows passing data to the template using standard block methods like 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 ?>