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!

 

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

 

Give 2.0 – Welcome Hint.css and Goodbye qTip2

In Give version 2.0+ we are deprecating  qTip2 (with backward compatibility, of course) and all tooltips (frontend + backend) will be generated with the new Give_Tooltips class. We’ve put a lot of work into this new class so it can handle all the various types of tooltips supported by hint.css, a pure CSS solution. Now you can create flexible tooltips based on your specific needs with a simple setup and the flexibility you expect from a professionally developed WordPress plugin.

Our hope is that this update frees you from having to spend time writing any complex code for your custom Give tooltips. As well, it will give your users a better experience and also add a little speed boost to your sites since no additional JS is needed. Finally, since this is a pure CSS solution, this update also reduces the chances of potential conflicts with other scripts. Let’s explore further:

The Types of Tooltips

You can create multiple types of tooltips by specifying different properties:

  1. Position:
    1. Top
    2. Top Right
    3. Top Left
    4. Right
    5. Left
    6. Bottom
    7. Bottom Right
    8. Bottom Left
  2. Status:
    1. Error
    2. Warning
    3. Info
    4. Success
  3. Size:
    1. Small
    2. Medium
    3. Large
  4. Display:
    1. Show always
    2. Show on mouse hover
  5. Style:
    1. Square edges
    2. Round Edges
  6. Animation:
    1. No animation
    2. Bounce animation

How to Create Tooltips in Give 2.0+

Here is a general code sample to create a tooltip with Give_Tooltip with Give 2.0+:

Give()->tooltips->render(array(
    // Tooltip tag.
    'tag'         => '',
    'tag_content' => '',

    // Set to link of anchor if tooltip tag is anchor.
    'link'        => '#',

    // Text for tooltip
    'label'       => '',

    // Value: top-right, top, top-left, right, left, bottom-right, bottom, bottom-left.
    'position'    => 'top',

    // Value: error, warning, info, success.
    'status'      => '',

    // Value: small, medium, large.
    'size'        => '',

    // Value: true/false.
    'show_always' => false,

    // Value: true/false
    'round_edges' => false,

    // Value: true/false
    'animate'     => true,

    // Attributes.
    'attributes'  => array(),

    // Value: true/false
    // If set to true then automatically core will set size for tooltip on basic of word count of label. 
    'auto_width'  => true,
));

There are also some helper functions to quickly create tooltips:

/* The function below also accepts an array */
// Output span with question icon.
Give()->tooltips->render_help(/* Tooltip Text */);

/* The function below also accepts an array */
// Output span.
Give()->tooltips->render_span(/* Tooltip Text */);

// Output link.
Give()->tooltips->render_link(array( /*tooltip setting values*/ ));

This update is just one of many optimizations we’ll be releasing in the next major version of Give. Stay tuned for more!

 

Give 1.8.9 Give_Notices Class Update

In Give version 1.8.9+ all core notices (frontend + backend) will be generated with the Give_Notices class. We’ve put a lot of work in refactoring this class to handle much more than just output. Now you can specify the type of notice, whether it’s dismissible, and of course customize the content.

Our hope is that this update frees you from having to spend time writing custom notice handlers. As well, it should give a little speed boost to your sites because all JS is included conditionally based on whether a dismissible notice appears or not. Let’s explore further:

The Types of Notices

  1. Auto dismissible notices: These type of notices will automatically hide after 5 seconds. These are useful when updating settings and showing a “Settings updated” notice or similar.
  2. Manually dismissible notices: These type of notices will be hide for specific time interval (24 hours, 1 week, etc) or permanently per user or for all users. These are useful for reminders or
    1. Quick (24 hrs.) dismissed notice.
    2. Permanently dismissed notice
    3. Custom (time interval in seconds) dismissed notice.

How to Create a New Notice

Example wp-admin notices types.

1. Admin notice:

General code sample to create a notice with Give_Notices

Give()->notices->register_notice(array(
    'id' => '' // Value: unique notice id
    'type' => '' // Value: error/warning/success/info/updated
    'description' => '' // Value: notice message content
    'auto_dismissible' => '' // Value: 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)
));

2. Frontend Notices:

Example frontend notice types.

  1. Render inline notice:

    give_output_error( 'error message', true, 'error' );
    give_output_error( 'warning message', true, 'warning' );
    give_output_error( 'success message', true, 'success' );
  2. Render error stored in session:

    give_set_error( 'error_one', 'Error: one' );
    give_set_error( 'error_two', 'Error: two' );
    give_set_error( 'error_three', 'Error: three' );
    
    // Render all session errors with this function
    // Call this function according to your DOM structure.
    Give()->notices->render_frontend_notices();

Moving Forward

Once the new notices class is released in 1.8.9 we will be refactoring our add-ons to use the new class. This will help to make our code DRYer and ensure we’re setting a good example for future Give developers. We hope you enjoy the new notice class refactor coming soon!