Add A Custom Form Field

Checkout forms are rendered and processed using the ce-checkout-form component. This component serializes both SureCart form controls and native form controls located inside when the form is submitted.

Adding an additional form field will let you do additional order validation, as well as append custom field data to the order when it's submitted.

Adding a Form Field Block

To add a form field to checkout, you'll want to add your own Gutenberg block and specify the parent as 'surecart/checkout-form' or 'surecart/form-section' (likely both).

Validating Client-Side

Client-side validation can be enabled through the browser's Constraint Validation API. You can enable it using props such as required, pattern, minlength, and maxlength. As the user interacts with the form control, the invalid attribute will reflect its validity based on its current value and the constraints that have been defined.

When a form control is invalid, the containing form will not be submitted. Instead, the browser will show the user a relevant error message.

All form controls support validation, but not all validation props are available for every component. Refer to a component's documentation to see which validation props it supports.

Note that validity is not checked until the user interacts with the control or its containing form is submitted. This prevents required controls from being rendered as invalid right away, which can result in a poor user experience. If you need this behavior, set the invalid attribute initially.

note

Client-side validation can be used to improve the UX of forms, but it is not a replacement for server-side validation. You should always validate and sanitize user input on the server!

Validating Server Side

When a form is first submitted, it's sent to validation on server side. Validation will let you check all the submitted data, including your own field for validation. This lets you check your field or combinations of fields to make sure the data submitted is valid. The checkout form will not submit if there are any validation errors.

add_filter('surecart/checkout/validate', 'my_custom_validation', 10, 3);

function my_custom_validation($errors, $fields, $checkout_form_id) {
    // check to see if it's valid
    $is_valid = my_check_valiation_function($fields['my_custom_field']);

    // if it's not valid, add our error message.
    if (!$is_valid) {
        $errors[] => [
            'code' => 'my_error_code',
            'message' => 'This field is not valid'
        ];
    }

    // make sure to return errors
    return $errors;
}

Transforming User Input

You may also want to dynamically add, update or pull data before an order is submitted. This lets you take the users input and transform or change it before being added to the order when it's submitted. This is run after all validation has passed. Any validation should occur in the surecart/checkout/validate filter.

add_filter('surecart/checkout/submit', 'my_custom_dynamic_field', 10, 2);

function my_custom_dynamic_field($fields, $checkout_form_id) {
    // transform user input
    $fields['my_custom_field'] = my_transform_function($fields['my_custom_field']);

    return $errors;
}, 10, 2);

Handling Order Success

When an order is submitted, your fields are saved in with the order's custom fields. Once an order has been successfully made, you can access your custom field data from the custom_fields key in the order. Note: this specific hook is an action where the previous have been filters.

add_action('surecart/checkout/complete', 'my_custom_action', 10, 2);

function my_custom_action($order, $checkout_form_id) {
    // only look for our field
    if ( empty($order['custom_fields']['my_custom_field'])) {
        return;
    }

    $my_field_value = $order['custom_fields']['my_custom_field'];
    do_something_with_value($my_field_value);
}

Handling Order Failure

Similar to order success, you can perform an action when the initial checkout order fails.

add_action('surecart/checkout/failed', 'my_custom_failure_action', 10, 2);

function my_custom_failure_action($order, $checkout_form_id) {
    // only look for our field
    if ( empty($order['custom_fields']['my_custom_field'])) {
        return;
    }

    $my_field_value = $order['custom_fields']['my_custom_field'];
    do_something_with_value($my_field_value);
}