Give 2.0 Database Updates Explained

Give 2.0 makes some significant updates to the database structure running behind the scenes. We’ve included an upgrade routine and are testing all scenarios to ensure that it’s both backwards compatible and runs smoothly going forward.

The following will help you to understand what’s going on with the structure and to plan accordingly. 

New Tables

We introduced six new tables to improve SQL query performance:

  1. {wp_prefix}_give_paymentmeta
    After 2.0 payment meta will be store in this table before it was saving in to {wp_prefix}_postmeta
  2. {wp_prefix}_give_formmeta
    After 2.0 form meta will be store in this table before it was saving in to {wp_prefix}_postmeta
  3. {wp_prefix}_give_logmeta
    After 2.0 log meta will be store in this table before it was saving in to {wp_prefix}_postmeta
  4. {wp_prefix}_give_customermeta has been renamed {wp_prefix}_give_donormeta
  5. {wp_prefix}_give_customer has been renamed to {wp_prefix}_give_donor
  6. {wp_prefix}_give_log
    After 2.0 log data will be store in this table. Pre-2.0 it was saving in to {wp_prefix}_posts

Database Upgrades

It’s important that you upgrade your database after 2.0 (make sure you back up first) in order to be sure you’re compatible with all the latest changes.

We have following database upgrades in 2.0:

  1. Update form meta
  2. Update offline email related settings
  3. Update payment meta
  4. Renamed core meta keys
    1. _give_payment_customer_id -> give_payment_donor_id
    2. _give_payment_user_email -> give_payment_donor_email
    3. _give_payment_user_ip -> give_payment_donor_ip
    4. Split the _give_payment_meta array to single meta keys:
      1. _give_payment_date
      2. _give_payment_currency
      3. _give_donor_billing_first_name
      4. _give_donor_billing_last_name
      5. _give_donor_billing_address1
      6. _give_donor_billing_address2
      7. _give_donor_billing_city
      8. _give_donor_billing_state
      9. _give_donor_billing_zip
      10. _give_donor_billing_country
    5. Store unique address to donor billing address.
    6. Move payment to {wp_prefix}_give_paymentmeta
    7. Move form to {wp_prefix}_give_formmeta
    8. Move Log data to {wp_prefix}_give_log and {wp_prefix}_give_logmeta
    9. Update donor
    10. Move user address to donor meta
    11. Create new donor meta for first name and last name
    12. Update rename donor table

Notes:

  1. Each upgrade is unique and logic connect to related upgrade only. Data will keep storing into old table till admin will complete upgrade.
  2. If admin stop upgrade and make change to move data then these new changes will not reflect to new meta.
  3. New logs will not appear on log list page till log upgrades complete.
  4. We are not deleting data during this upgrade for safety.

Payment Meta ( _give_payment_meta )

The following logic is connected to _give_payment_meta:

  1. We have a database upgrade to split this information to multiple unique key to make SQL query easy on them.
  2. Whenever we will update _give_payment_meta it will store into database and it will also split into multiple single keys ( See above: Database Upgrades 2b )
  3. Custom metadata which third party add-on storing into _give_payment_meta will not be affected. You can still get and set custom meta key inside _give_payment_meta.
  4. Post and pre upgrade when somebody gets _give_payment_meta meta key then it will pass through a filter which will overwrite the existing core meta key. That way the meta key will always contain the updated value.

Existing Code Compatiblity

If you have existing code that you’re concerned about compatibility moving forward here’s some information that should help clear things up.

Payment Meta

Currently in core we have following functions to get and update payment meta:

  1. give_get_payment_meta() ( wrapper for Give_Payment::get_meta() )
  2. Give_Payment::get_meta()
  3. give_get_meta()
  4. get_post_meta() (WP Core function)
  5. give_update_payment_meta() ( wrapper for Give_Payment::update_meta() )
  6. Give_Payment::update_meta()
  7. Give_update_meta()

If you are using any of the functions above within your code to store and retrieve payment meta then your code will be compatible with 2.0. If you are not using the functions above then likely you are fetching payment meta with a SQL query or another method which we don’t support.

Donor Meta

In 2.0 we are deprecating the Give_Customer and Give_DB_Customer_Meta classes. However, you can still use the deprecated classes within your code as there is built in backwards compatibility. We do recommend that you eventually update your code as best practice.

 

Give 2.0 Donor and User Meta Database Updates Explained

We want to keep everyone in the loop with what’s going on with the database updates within Give 2.0 which is now moving into the final testing phase. These are the following donor related updates we are doing in Give version 2.0 with backward compatibility:

  1. The donor related tables is renamed:
    1. {wp-prefix}_give_customer → {wp-prefix}_give_donor
    2. {wp-prefix}_give_customermeta → {wp-prefix}_give_donormeta
  2. The Give_Customer class is deprecated. Use the Give_Donor class instead.
  3. We are only storing donor ID to payment meta instead of user ID.
  4. Moving forward we are going to store donor metadata to {wp-prefix}_give_donormeta instead of WP’s {wp-prefix}_usermeta
    1. Current donor metadata stored in the usermeta table will be copied to the donormeta table using an upgrade routine.
    2. Previous donor metadata stored in the usermeta table will not be deleted. This is for backwards compatibility and a failsafe should the data migration be interrupted.
  5. Address updates:
    1. The donor’s billing address is currently (pre-2.0) only being saved to the donation payment meta. Moving forward in 2.0 the data is now saved to both the payment meta and the donor meta.
    2. If a repeat donor returns and enters a different billing address then it will save like before to the payment meta and add the new address to donormeta. In this case, the new address would be called “Billing Address 2” within the donor’s profile.
    3. The donor can now have multiple types for addresses.
      1. Add-on like Gift Aid will now store the additional “Gift Aid Address” to the donor meta.
      2. This paves the road for the future enhancement of allowing the donor to have both a billing address and physical address should admins want to collect the additional information.
    4. You can access all donor addresses from the Give_Donor object.
  6. A Give_Donor can connect to a WP_User for a variety of reasons including, but not limited to:
    1. Providing the user access to donors by using WordPress core functionality
    2. To increase the extensibility of Give with third-party plugins that creates user roles. Examples include:
      1. Membership plugins
      2. LMS platforms (course, study material)
      3. Content restriction plugins   
      4. Ecommerce platforms

If you have any questions be sure to ping us in our Slack community or in the comments!

 

Give 1.8.14 – Introducing the new Give_Donors_Query class

In Give version 1.8.14, We are introducing the new Give_Donors_Query class which will help developers to query donors more easily and efficiently with less code. [Read]

Here is a general code sample query parameters for Give_Donors_Query:

$donor = new Give_Donors_Query(array(
    'number'     => 20,
    'offset'     => 0,
    'paged'      => 1,
    'orderby'    => 'id',
    'order'      => 'DESC',
    'user'       => null,   // Single or array of user ids
    'email'      => null,   // Single or comma seperated emails
    'donor'      => null,   // Single or array of donor ids
    'meta_query' => array(),
    'date_query' => array(),
    's'          => null,   // search string with prefix name: or note:
    'fields'     => 'all', // Support donors (all fields) or valid column  as string or array
    'count'      => false, // Set to true to get donor count for current query
));

Another demo query for the Give_Donors_Query class:

1. Get donors and sort by total donation amount:

$donors = new Give_Donors_Query(array(
    'number'     => -1,
    'orderby'    => 'purchase_value',
));
$donors = $donors->get_donors();

2. Get donors and sort by total donation count:

$donors = new Give_Donors_Query(array(
    'number'     => -1,
    'orderby'    => 'purchase_count',
));
$donors = $donors->get_donors();

3. Get information about specific donors:

$donors = new Give_Donors_Query(array(
    'donor'    => array( 11, 45, 67 ),
));
$donors = $donors->get_donors();

4. Get the total number of donors:

$donors = new Give_Donors_Query(array(
    'number' => -1,
    'count' => true,
));
$donors = $donors->get_donors();

This class was created because we found it difficult and cumbersome to do more complex donor queries. We will continue to optimize the class as we move forward. Please let us know if you find any issues on GitHub.

 

Give 1.8.14 – Give_Notices Class Update

In Give version 1.8.9 we introduced the Notices API. In release 1.8.14 we are adding improvements to the API so that you can create non-dismissible notice without a close icon appearing [Read]. This type of notice should only be used for very important messages, like blockers, such as database updates and missing dependancies.

Here is a general code example to create a notice with the Give_Notices API:

Give()->notices->register_notice(array(
    'id' => '' // Value: unique notice id
    'type' => '' // Value: error/warning/success/info/updated
    'description' => '' // Value: notice message content
    'dismissible' => '' // Value: auto/true/false. if set to true then notice will auto class in 5 seconds
    'dismissible_type' => '' // Value: null/user/all
    'dismiss_interval' => '' // Value shortly/permanent/custom
    'dismiss_interval_time' => '' // Value: time interval in seconds (only need if dismiss_interval set to custom)
));

[Read]

If you want to create non-dismissible notice without close icon set dismissible to false.

Non dismissible notices without close icon

In addition to the new non-dismissible notice enhancement we have deprecated the auto-dismissible parameter for simply dismissible with backward compatibility.

We’re also working to create inline notices and other additional notice enhancements in the future so stay tuned!

 

Give 1.8.13 Tab Improvements & Conditional Field Changes

Give 1.8.13 introduces subtle improvements to the tabbed interface when editing a donation form. The improvements are summarized below along with a new requirement that developers should be aware in order to produce a seamless tabbed experience.

Added Unique Tab URLs

Each tab now has a unique URL denoted by a give-tab query parameter that updates on each tab change. This means that tabs can be navigated to directly, bookmarked, and most importantly, maintained after a page reload. For example, the URL of the Form Display tab would be structured as follows:
/wp-admin/post-new.php?post_type=give_forms&give_tab=form_display_options

Added Active Tab Persistence

Because each tab now has a unique URL, the active tab can be maintained after save. For example, if the active tab is Form Display when the form is published or updated, then the page will reload with Form Display as the active tab. The result is a more seamless experience, especially for users who save and refresh the screen often during the initial form build.

Tab detection is made possible by a $_GET['give-tab'] parameter that is detected server-side and included in the redirect after save.

Removed Conditional Fields Flicker

In previous versions of Give, conditional fields that should be hidden by default would flicker upon page load. This flicker occurred because conditional fields were being hidden via JavaScript after page load. As of Give 1.8.13, a give-hidden class is applied to conditional fields via PHP so that they are hidden by default, thus preventing any chance of flicker.

Developers Note This Important Change to Conditional Fields

When registering conditional settings in the future, developers should ensure that the 'wrapper_class' => 'give-hidden' is used in order to hide the conditional field by default. An example use case is provided below.

/**
 * Below are two field settings. If Custom Amount is enabled, then Minimum
 * Amount becomes visible. Note the use of 'wrapper_class' in the
 * conditional field to ensure Minimum Amount is hidden by default.
 */

// Regular field.
array(
    'name'        => __( 'Custom Amount', 'give' ),
    'description' => __( '...', 'give' ),
    'id'          => $prefix . 'custom_amount',
    'type'        => 'radio_inline',
    'default'     => 'disabled',
    'options'     => array(
        'enabled'  => __( 'Enabled', 'give' ),
        'disabled' => __( 'Disabled', 'give' ),
    ),
),

// Conditional field.
array(
    'name'          => __( 'Minimum Amount', 'give' ),
    'description'   => __( '...', 'give' ),
    'id'            => $prefix . 'custom_amount_minimum',
    'type'          => 'text_small',
    'data_type'     => 'price',
    'attributes'    => array(
        'placeholder' => $price_placeholder,
        'value'       => $custom_amount_minimum,
        'class'       => 'give-money-field',
    ),
    'wrapper_class' => 'give-hidden', // Note the use of 'wrapper_class'.
),
 

We’re Now Using ESLint for WordPress Coding Standards in GiveWP

WordPress has already defined Javascript Coding Standards which needs to be followed during development of WordPress Core, Plugins, or Themes. This allows developers to maintain the quality of the platform and even you can save time by getting rid of common JS errors.

Following WordPress Javascript Coding Standards using ESLint

To overcome JS errors and maintain quality for JS files as per the coding standards defined by WordPress, we have introduced ESLint in the upcoming release 1.8.12.

ESLint is a pluggable linting utility for Javascript which helps developers to get rid of common errors during development.

How to Configure ESLint

We’ve packaged Give Core with the ESLint config file. So, you need to worry much about it and just follow simple steps once and you’re done!

Step 1: Install Node Modules as defined in Give’s package.json

$ npm install

Step 2: Using ESLint

With Terminal:

  1. Open Terminal
  2. Type Command in format: eslint [options] file.js [file.js] [dir]
  3. You’ll get list of suggestions, if any:
Example of ESLint Suggestions

An example of ESLint suggestions

For Example,
$ eslint yourfile.js

With PHPStorm… please read on:

Configuring PHPStorm with ESLint

We use PHPStorm as our IDE of choice. If you use it as well, follow the below steps to configure ESLint with PHPStorm:

  1. Open PHPStorm and go to Preferences > Languages and Frameworks > Javascript > Code Quality Tools > ESLint
  2. Now, Tick the Enable checkbox.
  3. Set path for Node Interpreter and the ESLint Package, if it is not set by default.
Steps to configure ESLint in PHPStorm

Steps to configure ESLint in PHPStorm

ESLint suggestions in PHPStorm

ESLint suggestions in PHPStorm

That’s it! Now you’re all set up to code JavaScript in GiveWP using WordPress Coding Standards. Happy Coding! 🙂

 

Give 2.0 – Introducing an Improved Email System

In Give version 2.0+, we are making many enhancements to the core email settings. First off, all of the core emails now can be editing on a global or per form basis. As well, you can now preview and send test emails for all email types. We’ve put a lot of work into this new email API to make it flexible for both developers and WordPress backend managers.

Our hope is that this update frees you from having to spend time writing any complex code for your custom emails. As well, with the power to customize and preview emails

Let’s Explore Further:

Better email interface and easier testing. Previously you could only preview specific emails. In 2.0+ we developed the new Send Email and Preview Email features to reduce the amount of time it takes to check and test your emails.

Better email testing tools

Email testing tools

Quick change email notification status:

You can easily click on email notification status icon to the change notification status.

Quick Edit email notification status

Easy edit email notification status

Better email listings:

Now you can see all core or custom email at one place with brief information about them.

Email List

Email List

Per Email Settings

Now you will have more control on global and per form email settings.

Global email setting:

Global email setting

Global email setting

Per form email setting:

Per form email setting

Per form email setting

How to Create Custom Emails

To create a custom email notification you can easily extend the Give_Email_Notification class. You can then easily set the configuration for your email notification. You can find list of config options here: https://github.com/WordImpress/Give/blob/release/2.0/includes/admin/emails/abstract-email-notification.php#L45

You can also check out this snippet which we created for custom email notification: https://github.com/WordImpress/Give-Snippet-Library/blob/give20/email_api/email-customization/class-donor-gratitude-email.php

You can find core default notification here: https://github.com/WordImpress/Give/tree/release/2.0/includes/admin/emails