Donation Form Lifecycle

Donation Form Lifecycle Visual

Donation Form Lifecycle Visual.pdf

Donation Form Rendering

Our donation form is a react application. On the server, we construct a form schema using our Fields API, which is later converted to JSON for the front-end to consume. In GiveWP 3.0+ we build our forms using our visual form builder, storing our blocks and settings in the database as JSON. The form schema is generated based on these blocks and settings from the form builder. The final rendering process in the browser uses a unique cascading scripts approach, utilizing our form template API.

Script loading order:

1. Dependencies like React from WordPress
2. Our donation form registrar scripts (including gateways and form templates)
3. Form design layout scripts (classic, multi-step, etc.)
4. Form extension scripts (fee recovery, form field manager, etc.)
5. Payment gateway scripts
6. Donation form app

Donation Form Rendering Hooks

---

givewp_donation_form_schema

/**
 * This is the entry point for the donation form schema, after it was built from blocks via the visual form builder.
 *
 * @param Give\Framework\FieldsAPI\DonationForm $form
 * @param int $formId
 * @param array $blockNodeRelationships
 */
do_action('givewp_donation_form_schema', $form, $formId, $blockNodeRelationships);

givewp_donation_form_enqueue_scripts

/**
 * This is the entry point for enqueuing scripts into the GiveWP donation form rendering process using the native WordPress wp_enqueue_script. 
 * This is typically used for creating a custom field template
 */
do_action('givewp_donation_form_enqueue_scripts');

givewp_donation_form_block_render

/**
* This filter is for converting a custom form builder block into a Fields API Node.
*
* @param Give\Framework\FieldsAPI\Contracts\Node|null $customField The custom field.
* @param Give\Framework\Blocks\BlockModel $block The block model.
* @param int $blockIndex The block index.
* @param int $formId The form ID.
* @return Give\Framework\FieldsAPI\Contracts\Node|null
*/
$customField = apply_filters(
    "givewp_donation_form_block_render_{$blockName}",
    $customField,
    $block,
    $blockIndex,
    $formId
);

givewp_donation_confirmation_receipt_viewing

/**
 * Fires before the donation confirmation receipt view is rendered.
 *
 * @param Give\Donations\Models\Donation $donation
 */
do_action('givewp_donation_confirmation_receipt_viewing', $donation);

Donation Form Processing

When a donation form has been submitted, it goes through a series of processing steps.

1. Validate the form request (including all fields). Exit with errors if anything is not valid.
2. Determine the donor associated with the form request. Either retrieve an existing donor or create a new one.
3. Determine if donation type is one-time or subscription (recurring)
4. Create a donation model (and subscription model if donation type is subscription) with status(es) of pending
5. Persist custom fields and field api scopes
6. Request moves to the Payment Gateway including the following data: donation model, subscription model (if applicable), and gateway data
7. Payment gateway processes the donation and/or subscription using their API and is responsible for completing the form request. Some gateways need to finish their request via a webhook and will mark the donation in a processing status until then.
8. When completed successfully, the donation form will navigate to the donation confirmation view.

Donation Form Processing Actions

---

givewp_donation_form_processing_start

/**
 * Fires at the start of donation form processing, before any data is processed.
 *
 * @param  Give\DonationForms\DataTransferObjects\DonateControllerData  $formData
 * @param  string  $gatewayId
 */
do_action('givewp_donation_form_processing_start', $formData, $gatewayId);

givewp_donation_form_processing_donation_created

/**
 * Fires after a donation is created during donation form processing.
 *
 * @param  Give\Donations\Models\Donation  $donation
 * @param  Give\Subscriptions\Models\Subscription|null  $subscription
 */
do_action('givewp_donation_form_processing_donation_created', $donation, $subscription);

givewp_donation_form_processing_subscription_created

/**
 * Fires after a subscription is created during donation form processing.
 *
 * @param  Give\Subscriptions\Models\Subscription  $subscription
 * @param  Give\Donations\Models\Donation  $donation
 */
do_action('givewp_donation_form_processing_subscription_created', $subscription, $donation);

givewp_donation_form_processing_donor_created

/**
 * Fires after a donor is created during donation form processing.
 *
 * @param  Give\Donors\Models\Donor  $donor
 * @param  int  $formId
 */
do_action('givewp_donation_form_processing_donor_created', $donor, $formId);

givewp_donation_form_processing_custom_fields_stored

/**
 * Fires after custom fields have been stored/processed
 *
 * @param Give\DonationForms\Models\DonationForm $form
 * @param array $customFields
 * @param Give\Donations\Models\Donation $donation
 * @param Give\Subscriptions\Models\Subscription|null $subscription
 */
do_action('givewp_donation_form_processing_custom_fields_stored', $form, $customFields, $donation, $subscription)