Seamless Donations actions and filters
Seamless Donations 4.0 and above support a wide range of actions and filters, allowing you to modify the behavior of the plugin on the fly. Please do not modify the core plugin. Regular plugin updates will overwrite any changes you make to the core. If you need a special hook, don’t hesitate to ask.
Front-end form filters
The following hooks allow you to safely modify every aspect of the front-end form via filters. Each of these is passed the form array, which can be modified, and then returned to the form generator.
- seamless_donations_form_donation_section: modifies the form array for the donation section
- seamless_donations_form_tribute_section: modifies the form array for the tribute section
- seamless_donations_form_donor_section: modifies the form array for the donor information section
- seamless_donations_form_billing_section: modifies the form for the donor billing section
- seamless_donations_form_paypal_section: modifies the hidden fields for PayPal donations
- seamless_donations_form_submit_section: modifies the submit section
- seamless_donations_form_section_order: processes after all form sections are loaded into the $form array
To control the form, you will need to understand how to construct the form array, which uses the constructs described in Seamless Donations Forms Engine Codex.
- seamless_donations_shortcode_features: allows additions and extensions to basic seamless-donations shortcode.
- seamless_donations_payment_post_data: called before sending post data to PayPal for processing
- seamless_donations_challenge_response_request: fires after the submit form is submitted. If filter is used, and it fails, an “Invalid response to challenge. Are you human?” is displayed
- seamless_donations_paypal_ipn_processing_complete: triggers after IPN processing complete. Does not necessarily indicate successful processing.
To properly use the admin hooks, it’s important to understand the naming conventions used.
- Format for each admin tab is seamless_donations_admin_[tab-name]. There are no underscores in the tab name
- The page slug gets the same name
- The file containing the admin tab is named [tab-name] and is located in the admin folder
- The tab configuration function seamless_donations_admin_[tab-name] calls seamless_donations_admin_[tab-name]_menu to set up the menu for the tab.
- Each section in the tab is defined by the function seamless_donations_admin_[tab-name]_section_[section-name]. No underscores in the section name.
- Current tab names are donations, donors, templates, forms, funds, logs, main, settings, and thanks.
The following filter is called when any of the admin forms are submitted. Called right at the beginning of the form submission/validation process, format is:
- validate_page_slug_seamless_donations_admin_[tabname]_callback: gets passed three parameters, $_submitted_array, $_existing_array, $_setup_object
These actions are now available:
- seamless_donations_admin_[tab-name]_before: called before the tab and menu are instantiated
- seamless_donations_admin_[tab-name]_after: called after all of the other tab display operations are completed
- seamless_donations_admin_settings_before_tweaks: specifically applies to the settings tab to allow elements to be placed before the Tweaks and Debug mode section (which generally should be at the bottom of the full list of settings)
These filters are now also available:
- seamless_donations_admin_[tab-name]_menu: passes the full menu array prior to instantiating the menu
- seamless_donations_admin_[tab-name]_section_[section-name]: passes the section definition array prior to instantiating the section
- seamless_donations_admin_[tab-name]_section_[section-name]_options: passes the option definition array prior to instantiating the options list
These filters are enormously powerful because they allow complete control of everything on the admin UI tabs for Seamless Donations.
The actual contents of the arrays are managed by Admin Page Framework (a product framework licensed by Seamless Donations) so you can easily add (or remove) a wide variety of features at any point in the admin page. Documentation for Admin Page Framework can be found here.
The following filters modify the email in email.php before it’s sent out.
- seamless_donations_email_complete_body: takes in the body and the donation ID and provides back the body
- seamless_donations_email_subject: takes in the subject and the donation ID and provides back the subject
Admin forms validation filter
You can process admin form validations for any button pressed in the Seamless Donations admin UI. The filter is validate_page_slug_[page_slug_name]. For example, if a page’s slug is seamless_donations_funds, it calls the filter validate_page_slug_seamless_donations_funds. The filter takes three parameters:
- the array of data submitted with the form
- the array of data already in the database associated with the form
- the setup object, which is the class (for things like setting error messages)
Custom post type filters
Fund, donor, and donation custom post types have a number of filters you can use:
- seamless_donations_donors_setup: passes the custom post type array for setup
- seamless_donations_donors_type_setup: passes the taxonomy array for setup
- seamless_donations_donor_header_style: passes CSS that helps customize the donor list header
- seamless_donations_donor_header_array: passes an array that contains the name of the donor list header fields
- seamless_donations_donations_type_setup: passes the taxonomy array for setup
- seamless_donations_donations_setup: passes the custom post type array for setup
- seamless_donations_donation_header_style: passes CSS that helps customize the donation list header
- seamless_donations_donation_header_array: passes an array that contains the name of the donation list header fields
- seamless_donations_funds_setup: passes the custom post type array for setup
- seamless_donations_funds_type_setup: passes the taxonomy array for setup
Pre-4.0 legacy hooks
- dgx_donate_giving_levels: contains an array of integer giving level values fed to the giving-level system
- dgx_donate_item_name: allows you to set the item_name parameter passed to PayPal
- dgx_donate_thank_you_email_body: added in 4.0.11, but works with the legacy text-only mailer, takes in body text of email and returns back a possibly modified body text