Skip to content

Confirmation Dialogs

The Hyvä confirmation dialogs are built on top of the modal dialogs.
Everything written previously about modal dialogs also applies to confirmation dialogs.

Available since 1.1.13

Confirmation dialogs are available since version 1.1.13 of Hyva_Theme. If you are using an older version, be sure to upgrade the theme module.

To create a confirmation modal instance in PHP, use the confirm method on the modal view model:

$confirmation = $modalViewModel->confirm(__('Are you sure?')

Then customize the dialog as needed just like a regular Hyvä modal.

The default confirmation modal template is Hyva_Theme::modal/confirmation.phtml.

Triggering actions

To trigger some action after if the OK button was clicked, chain it to the show() method with a promise. If the callback retrieves a true value, the user confirmed the dialog. If the callback retrieves a falsy value, the confirmation dialog was cancelled.

Simple Example

This simple example logs OK or Cancel to the browser console, depending on the users selection.
I a real project, the callback would probably be a method on an Alpine.js component, or maybe dispatch an event, rather than this one line example.

<div x-data="hyva.modal()">
    <?php $confirmation = $modalViewModel->confirm(__('Are you sure?')) ?>
    <button @click="<?= $confirmation->getShowJs() ?>.then(result => result && console.log('OK') || console.log('Cancel'))"
            type="button" class="btn mt-2" aria-haspopup="dialog">Show</button>
    <?= $confirmation ?>
</div>

Customizing Confirmation Dialogs

Four confirmation specific methods are available in addition to the same methods as modal dialogs:

withTitle($title)

The title for the confirmation dialog is specified when the confirm('the title') method is called on the modal view model.
But it can also be specified using the withTitle method.

The title is escaped by the confirmation dialog template:

<div class="font-bold text-xl"><?= $escaper->escapeHtml($block->getData('title')) ?></div>

withDetails($details)

Specifying a confirmation dialog details is optional.
If details are specified, they are rendered between the title and the buttons.

<?php if ($block->hasData('details')): ?>
    <div>
        <?= /** @noEscape */ $block->getData('details') ?>
    </div>
<?php endif; ?>

The details are not escaped, so they may contain HTML.

setContent() vs. setDetails()

The confirmation modal instance also has a method setContent(). The setContent() method is used to specify the complete contents, and, if set, will cause the template to not be rendered.
This allows for a large degree of customizability, but can be confusing.

As a rule of thumb, be sure to use setDetails() on confirmation dialogs.

withOKLabel($okLabel)

The default label for the confirm button is "OK". This can be changed using the withOKLabel() method.
The button labels are escaped during rendering:

<?= $escaper->escapeHtml($block->getData('ok') ?: __('OK')) ?>

withCancelLabel($cancelLabel)

The default label for the cancel button is "Cancel". This can be changed using the withCancelLabel() method.
The button labels are escaped when rendered:

<?= $escaper->escapeHtml($block->getData('cancel') ?: __('Cancel')) ?>

Changing the confirmation template file

Or course the confirmation dialog templates can be customized using a theme override, like any other template.
However, if a unique template is required for a specific dialog, it can be set with the setTemplate method:

$confirmation->withTemplate('Hyva_Theme::modal/custom-confirmation.phtml');

Dialogs with more than two choices

It is possible to create custom confirmation dialogs with more than two buttons.
The value the show promise resolves to is the argument passed to the hide method.
This allows building dialogs with more than two choices using the modal view model.

This requires a custom template.

Be sure to pass distinct values to the hide() method for each button to indicate the users choice.

    <button @click="hide('a')" type="button" class="btn">
        <?= $escaper->escapeHtml(__('Option A')) ?>
    </button>
    <button @click="hide('b')" type="button" class="btn">
        <?= $escaper->escapeHtml(__('Option B')) ?>
    </button>
    <button x-focus-first @click="hide('c')" type="button" class="btn btn-primary">
        <?= $escaper->escapeHtml(__('Option C')) ?>
    </button>

Confirmation dialogs without the view model (Alpine.js only)

It is possible to use the Hyvä modals without the PHP view model to create confirmation dialogs.

<div x-data="hyva.modal()">
    <button @click="show($event).then(result => console.log(result))"
            type="button" class="btn mt-2" aria-haspopup="dialog">Show</button>

    <div x-cloak x-spread="overlay()" x-bind="overlay()"
         class="fixed inset-0 flex items-center justify-center text-left bg-black bg-opacity-50">

        <div x-ref="dialog" role="dialog" aria-labelledby="the-label"
             class="inline-block max-h-screen overflow-auto bg-white shadow-xl rounded-lg p-10 text-gray-700">
            <div id="the-label">Are you sure?</div>
            <div>Think before you click...</div>
            <div class="mt-20 flex justify-between gap-2">
                <button @click="cancel" type="button" class="btn">Cancel</button>
                <button x-focus-first @click="ok" type="button" class="btn btn-primary">OK</button>
            </div>
        </div>

    </div>
</div>

Important

Be sure to use a unique x-ref name if there is more than one modal dialog on the page.

Examples

What follows is a collection of examples.

Confirmation dialog with only details

<div x-data="hyva.modal()">
    <?php $confirmation = $modalViewModel->confirm()
                              ->withDetails($escaper->escapeHtml(__('Are you sure?'))) ?>
    <button @click="<?= $confirmation->getShowJs() ?>.then(result => console.log(result))"
            type="button" class="btn mt-2" aria-haspopup="dialog">Show</button>
    <?= $confirmation ?>
</div>

Confirmation dialog with title and details

<div x-data="hyva.modal()">
    <?php $confirmation = $modalViewModel->confirm(__('Are you sure?'))
                              ->withDetails('<em>Think before clicking.</em>') ?>
    <button @click="<?= $confirmation->getShowJs() ?>.then(result => console.log(result))"
            type="button" class="btn mt-2" aria-haspopup="dialog" aria-haspopup="dialog">Show</button>
    <?= $confirmation ?>
</div>

Confirmation dialog with custom button labels

<div x-data="hyva.modal()">
    <?php $confirmation = $modalViewModel->confirm(__('Is that all?'))
                              ->withOKLabel(__('Yes'))
                              ->withCancelLabel(__('No')) ?>
    <button @click="<?= $confirmation->getShowJs() ?>.then(result => console.log(result))"
            type="button" class="btn mt-2" aria-haspopup="dialog">Show</button>
    <?= $confirmation ?>
</div>

Under the hood:

For further information to see how the modal system works under the hood, please check out the following PHP classes:

  • \Hyva\Theme\ViewModel\Modal::confirm()
  • \Hyva\Theme\Model\Modal\ConfirmationBuilderInterface