Evaluation examples

The evaluation API serves a variety of purposes across different contexts, including the integration with both new and existing Magewire components. Additionally, starting from version 1.1.13, it offers compatibility with existing or custom Place Order Services, which can be seamlessly integrated with payment methods as needed.

Browsing through the documentation will provide you with a basic understanding of its functionalities. However, for a deeper comprehension, we've included a few examples to illustrate potential applications. These examples will offer insight into the possibilities that can be achieved through its implementation.

New features since 1.1.13 will be marked.

Credit card authorization

In this case, a payment method necessitates extra authorization before proceeding to the next step or placing the order. Custom validation will be triggered upfront, with a loading indicator displayed until completion. If validation fails, an error message will appear within the component. Alternatively, the customer will proceed to the next step or the order placement process will commence.

1. Create the component

In this case we're going to create a very straightforward Magewire component implementing the EvaluationInterface and have a single field that needs to be validated when hitting the primary navigation button.

<?php

class Cc extends \Magewirephp\Magewire\Component implements \Hyva\Checkout\Model\Magewire\Component\EvaluationInterface
{
    public function evaluateCompletion(\Hyva\Checkout\Model\Magewire\Component\EvaluationResultFactory $resultFactory): \Hyva\Checkout\Model\Magewire\Component\Evaluation\EvaluationResult
    {
        /*
         * Since 1.1.13
         * 
         * Direct the frontend to execute "validateMyCustomCcComponent" and
         * trigger an error message event in case of failure.
         */
        return $resultFactory->createValidation('validateMyCustomCcComponent')
            ->withFailureResult(
                $resultFactory->createErrorMessageEvent()
                    ->withCustomEvent('payment:method:error')
                    ->withMessage('Invalid credit card details provided. Please try again.')
                    ->withVisibilityDuration(5000)
             );

        /*
         * Before 1.1.13
         * 
         * Either need to provide a mock success result or not implement the EvaluationInterface.
         */
        return $resultFactory->createSuccess();
    }
}

2. Inject the component into the checkout

In this scenario, we assume that this pertains to a payment method requiring registration with an alias corresponding to the payment method code. Further instructions on implementing a custom payment method can be found here.

As it is a payment method, the checkout framework will automatically search for a corresponding block and attempt to render its template as soon as it is found.

<!-- File: view/frontend/layout/hyva_checkout_components.xml -->

<referenceBlock name="hyva.checkout.components">
    <block name="checkout.payment.method.cc"
           as="cc"
           template="My_Example::checkout/payment/method/cc.phtml"
    >
        <arguments>
            <argument name="magewire" xsi:type="object">
                \My\Example\Magewire\Checkout\Payment\Method\Cc
            </argument>
        </arguments>
    </block>
</referenceBlock>

3. Create the frontend validation

Now we need to inject a custom validator. While we could include it directly in the PHTML of the component, it's advisable to inject it into either the hyva.checkout.api-v1.after or hyva.checkout.init-evaluation.after containers for better organization and maintainability.

<script>
    /*
     * Since 1.1.13
     * 
     * We wait for the evaluation API to be initialized where after
     * we register a validator named "validateMyCustomCcComponent".
     */
    window.addEventListener('checkout:init:evaluation', event => {
        hyvaCheckout.evaluation.registerValidator('validateMyCustomCcComponent', (element, component) => {
            return Math.random() < 0.5 // Randomly return true of false.
        })
    })

    // Before 1.1.13
    window.addEventListener('checkout:init:validation', event => {
        hyvaCheckout.validation.register('validateMyCustomCcValidation', () => {
            const result = Math.random() < 0.5 // Randomly return true of false.

            if (result) {
                return true
            }

            // Dispatch a custom message to the payment method messenger block.
            hyvaCheckout.messenger.dispatch(
                'payment:method',
                'Invalid credit card details provided. Please try again.'
            )

            return false
        })
    })
</script>