Frontend Evaluation API for Hyvä Checkout

Since: 1.1.0

The hyvaCheckout.evaluation sub-namespace provides methods for registering frontend validators that integrate with the backend Evaluation API. This enables Magewire components to define validation rules on the server that execute JavaScript validation logic on the client, creating a unified validation system across the checkout.

How Frontend Evaluation Works

When a Magewire component implements EvaluationInterface and returns a validation result type, the Hyvä Checkout Frontend API looks for a matching registered validator by name. The backend defines what validation should occur and what happens on failure, while the frontend defines how the validation executes using JavaScript.

For a complete overview of the Evaluation system including backend implementation, result types, and practical examples, see the dedicated backend Evaluation API documentation.

registerValidator

hyvaCheckout.evaluation.registerValidator registers a named JavaScript validator function that pairs with a backend Validation result type. When the backend component returns a validation result matching the registered name, the Frontend API executes the corresponding JavaScript callback.

Since: 1.3.5

Parameters:

• name (string) - A unique validator name that must match the name used in the backend createValidation() call.
• callback (function) - The validator callback function. Receives (component, element, evaluation) parameters and must return true (valid) or false (invalid).

Returns:

• Promise - Resolves when the validator is successfully registered.

Backend Component Example

The following PHP code shows a Magewire component that defines a validation result type named my-unique-validator. When validation fails, the backend specifies the failure behavior (console log and warning dialog).

Backend: Magewire component with EvaluationInterface

Magewire Component Implementing EvaluationInterface

<?php

namespace Vendor\Module\Magewire;

use Magewirephp\Magewire\Component;
use Hyva\Checkout\Model\Magewire\Component\EvaluationInterface;
use Hyva\Checkout\Model\Form\EntityFormInterface;
use Hyva\Checkout\Model\Magewire\Component\Evaluation\EvaluationResultFactory;

class MyComponent extends Component implements EvaluationInterface
{
    /**
     * Define validation result that triggers frontend validator registration lookup.
     * The 'my-unique-validator' name must match the frontend registerValidator() name.
     */
    public function evaluateCompletion(EvaluationResultFactory $resultFactory): EntityFormInterface
    {
        return $resultFactory->createValidation('my-unique-validator')
            // Optional: Define what happens when the frontend validator returns false
            ->withFailureResult(
                $resultFactory->createConsoleLog('My unique validator failed... please try again.')
            )
            ->withFailureResult(
                $resultFactory->createMessageDialog('Validation Failure')
                    ->withMessage('My unique validator failed... please try again.')
                    ->asWarning()
            );
    }
}

Frontend Validator Registration Example

The following JavaScript registers the frontend validator that pairs with the backend component above. The validator name my-unique-validator must exactly match the name passed to createValidation() in PHP.

Frontend: Registering the JavaScript validator callback

JavaScript Validator Registration

<script>
    (() => {
        // Wait for Frontend API initialization before registering
        hyvaCheckout.api.after(() => {
            // Register validator with name matching backend createValidation() call
            hyvaCheckout.evaluation.registerValidator(
                'my-unique-validator',
                async (component, element, evaluation) => {
                    // Implement custom validation logic here
                    // component: The Magewire component instance
                    // element: The DOM element associated with the component
                    // evaluation: The evaluation context object

                    // Return true for valid, false for invalid
                    // On false, the backend-defined withFailureResult() actions execute
                    return true;
                }
            ).then(() => console.log('my-unique-validator registered successfully.'));
        });
    })();
</script>