Custom checkout fields

Sunshine Photo Cart allows you to customize the checkout process by adding or removing fields. This guide will walk you through the steps to add custom fields to the checkout, using the filters provided in the SPC_Cart class. We will also document all available field types to help you create the fields that best suit your needs.

Understanding the Checkout Fields Structure

The fields are organized into sections, such as contact, delivery, shipping, and payment. Each section contains an array of fields with specific attributes.

Here's a simplified representation of how fields are structured:

$fields['section_id'] = array(
    'name'   => 'Section Name',
    'fields' => array(
        array(
            'id'       => 'field_id',
            'type'     => 'field_type',
            'name'     => 'Field Name',
            'required' => true_or_false,
            'default'  => 'default_value',
            // Additional attributes...
        ),
        // More fields...
    ),
);

Learn how to add this custom code to your WordPress website

Adding Custom Fields Using Filters

To add custom fields to the checkout, you can hook into the sunshine_checkout_fields filter. Here's how you can do it:

  1. Hook into the Filter: Use the add_filter function to hook your custom function into the sunshine_checkout_fields filter.
  2. Modify the Fields Array: In your custom function, add or modify fields within the $fields array.
  3. Return the Modified Fields: Ensure your function returns the modified $fields array.

Example: Adding a Custom Field to the Contact Section

Let's add a custom "Company Name" field to the contact section.

add_filter( 'sunshine_checkout_fields', 'add_custom_company_field' );
function add_custom_company_field( $fields ) {
    // Define the new field
    $company_field = array(
        'id'       => 'company_name',
        'type'     => 'text',
        'name'     => __( 'Company Name', 'sunshine-photo-cart' ),
        'required' => false,
        'default'  => '',
        'size'     => 'full',
    );

    // Insert the new field into the 'contact' section
    $fields['contact']['fields'][] = $company_field;

    return $fields;
}

Learn how to add this custom code to your WordPress website

In this example:

  • We hooked the add_custom_company_field function to the sunshine_checkout_fields filter.
  • We created a new field array $company_field.
  • We inserted the new field into the contact section's fields array.
  • We returned the modified $fields array.

Example: Adding a New Section with Custom Fields

You can also add a completely new section to the checkout.

add_filter( 'sunshine_checkout_fields', 'add_custom_survey_section' );
function add_custom_survey_section( $fields ) {
    // Define the new section
    $fields['survey'] = array(
        'name'   => __( 'Customer Survey', 'sunshine-photo-cart' ),
        'fields' => array(
            array(
                'id'       => 'how_did_you_hear',
                'type'     => 'select',
                'name'     => __( 'How did you hear about us?', 'sunshine-photo-cart' ),
                'required' => true,
                'options'  => array(
                    'google'   => 'Google',
                    'friend'   => 'Friend',
                    'social'   => 'Social Media',
                    'other'    => 'Other',
                ),
            ),
        ),
    );

    return $fields;
}

Learn how to add this custom code to your WordPress website

In this example:

  • We added a new section called survey.
  • We defined two custom fields within this section.
  • We returned the modified $fields array.

Available Field Types

When adding custom fields, you can choose from several field types. Each field type has specific attributes and expected values.

Common Attributes

  • id (string): Unique identifier for the field.
  • type (string): Type of field (see available field types below).
  • name (string): Label displayed for the field.
  • required (bool): Whether the field is required.
  • default (mixed): Default value for the field.
  • size (string): Size of the field ('full', 'half', etc.).
  • options (array): Options for select, radio, or checkbox fields.
  • visible (bool): Whether the field is visible.
  • autocomplete (string): Autocomplete attribute for the field.
  • description (string): Additional description displayed below the field.

Field Types

Below are the available field types you can use:

1. Text

Single-line text input.

array(
    'id'   => 'text_field',
    'type' => 'text',
    'name' => __( 'Text Field', 'sunshine-photo-cart' ),
);

2. Email

Email input field, which validates email addresses.

array(
    'id'   => 'email_field',
    'type' => 'email',
    'name' => __( 'Email Field', 'sunshine-photo-cart' ),
);

3. Password

Password input field.

array(
    'id'   => 'password_field',
    'type' => 'password',
    'name' => __( 'Password Field', 'sunshine-photo-cart' ),
);

4. Telephone

Telephone input field.

array(
    'id'   => 'phone_field',
    'type' => 'tel',
    'name' => __( 'Phone Field', 'sunshine-photo-cart' ),
);

5. Textarea

Multi-line text input.

array(
    'id'   => 'textarea_field',
    'type' => 'textarea',
    'name' => __( 'Textarea Field', 'sunshine-photo-cart' ),
);

6. Radio

Radio buttons for selecting one option from multiple choices.

array(
    'id'      => 'radio_field',
    'type'    => 'radio',
    'name'    => __( 'Radio Field', 'sunshine-photo-cart' ),
    'options' => array(
        'option1' => __( 'Option 1', 'sunshine-photo-cart' ),
        'option2' => __( 'Option 2', 'sunshine-photo-cart' ),
    ),
);

7. Checkbox

Single checkbox or multiple checkboxes.

// Single checkbox
array(
    'id'   => 'checkbox_field',
    'type' => 'checkbox',
    'name' => __( 'Checkbox Field', 'sunshine-photo-cart' ),
);

// Multiple checkboxes
array(
    'id'      => 'checkboxes_field',
    'type'    => 'checkbox',
    'name'    => __( 'Checkboxes Field', 'sunshine-photo-cart' ),
    'options' => array(
        'option1' => __( 'Option 1', 'sunshine-photo-cart' ),
        'option2' => __( 'Option 2', 'sunshine-photo-cart' ),
    ),
);

8. Select

Dropdown select field.

array(
    'id'      => 'select_field',
    'type'    => 'select',
    'name'    => __( 'Select Field', 'sunshine-photo-cart' ),
    'options' => array(
        'option1' => __( 'Option 1', 'sunshine-photo-cart' ),
        'option2' => __( 'Option 2', 'sunshine-photo-cart' ),
    ),
);

9. HTML

Custom HTML content.

array(
    'id'   => 'html_content',
    'type' => 'html',
    'html' => '<p>Your custom HTML content here.</p>',
);

Conditional Logic for Fields

You can show or hide fields based on the values of other fields using the conditions attribute.

Example: Conditional Field

phpCopy codearray(
    'id'       => 'conditional_field',
    'type'     => 'text',
    'name'     => __( 'Conditional Field', 'sunshine-photo-cart' ),
    'required' => true,
    'conditions' => array(
        array(
            'field'   => 'trigger_field_id',
            'compare' => '==',
            'value'   => 'specific_value',
            'action'  => 'show',
        ),
    ),
);

In this example, the conditional_field will only be shown if trigger_field_id equals specific_value.

Validating Custom Fields

Sunshine Photo Cart automatically validates required fields and fields with specific types like email. For custom validation, you can hook into the sunshine_validate_{field_type} filter.

Example: Custom Validation for a Text Field

add_filter( 'sunshine_validate_text', 'custom_text_field_validation', 10, 3 );
function custom_text_field_validation( $error, $value, $field ) {
    if ( $field['id'] == 'custom_text_field' && strlen( $value ) < 5 ) {
        return __( 'The text must be at least 5 characters long.', 'sunshine-photo-cart' );
    }
    return $error;
}

Learn how to add this custom code to your WordPress website

Saving Custom Field Data

Any fields you add will automatically be saved to the metadata for the order, no additional steps are necessary.

Using Custom Data

You can use the sunshine_create_order hook which is passed $order:

add_action( 'sunshine_create_order', 'custom_create_order_action', 10, 1 );
function custom_create_order_action( $order ) {
    $custom_field = $order->get_meta_value( 'custom_field_id' );    
    if ( $custom_field ) {
        // Do something here.
    }
}

Learn how to add this custom code to your WordPress website

Including custom order data in admin order details screen

You can use the sunshine_admin_after_order_general hook to output your custom data:

add_action( 'sunshine_admin_after_order_general', 'show_custom_order_meta_admin', 10, 1 );
function show_custom_order_meta_admin( $order ) {
    $custom_field = $order->get_meta_value( 'custom_field_id' );    
    if ( $custom_field ) {
        echo '<p>Custom Field Name: ' .  $custom_field . '</p>';
    }
}

Learn how to add this custom code to your WordPress website

Still need help?

If you have not yet found your answer in the documentation articles, please contact support

Contact support