How To Create Your Own Give Shortcode

Have you ever wanted to build your own Give shortcode? This article will explain why, how, and even a sample of what to build.

We’ve told you before that Give is more than simply a donation button. But as we alluded to at the end of that article, besides awesome out-of-the-box features, Give is also extremely extensible.

How Does Give Provide Developers Extensibility?

Give provides developers with over 700 hooks (236 actions and 505 filters just in the core Give code at the time of writing) to extend Give. These hooks make it simple for a skilled developer to spend some time customizing the plugin, without having to worry about those changes being overwritten in future versions of the plugin.

In addition to hooks, one of the selling points of Give is that you own your data. It’s all saved right there in the WordPress database. So the combination of extending Give via actions and filters, with the right know-how, you can tap into your donation data to display dynamic donation-related content anywhere on your site!

One way developers can extend Give using those hooks in conjunction with that wealth of stored data is by writing their own shortcodes. But first, why?

Why Build Your Own Custom Shortcode?

When customizing your site, you want to code for the benefit of the non-coders. Shortcodes are a fantastic way to allow even the least code-adept user a method for displaying dynamic content on your site. The last thing you want is a call every Monday morning where you have to go and update the progress of the donation drive on the home page, because Bob in accounting doesn’t know how to code.

It’s always guys in accounting named Bob.

So if you bake in a custom shortcode, and teach Bob how to use it, you can prevent that awkward returned-a-phone-call-with-a-text moment every Monday morning.

In all seriousness, the more we can empower end-users to create dynamic content, the more we can, y’know, democratize generosity.

Shortcodes take complex info stored in a database and make it accessible, even to guys like Bob.

Sample Custom Shortcode Walkthrough

Here’s a shortcode that we whipped up for a user on our Priority support (because we LIKE to go all-out for our customers!). It displays donation progress for one or multiple forms:

First, check out our repo to review the code itself.

Following along by line number, the entire shortcode is built in the my_give_display_earnings_shortcode() function on line 19. Inside of that function, the $total variable (line 20) defaults to all give earnings by finding that data from the option saved in the database.

Next, the $atts variable sets the shortcode attributes on line 22 and following:

1. total_goal (which defaults to 10,000),
2. link (which defaults to false),
3. form_id (which defaults to false),
4. multi_id (which defaults to an empty string),
5. message_before (which is the text output before the $total, and defaults to ‘So far, we have raised ‘),
6. message_between (which is the text output after the $total, and defaults to ‘ toward our goal of ‘),
7. message_after (which is the text output after the ‘total_goal’ content and defaults to ‘! ‘),
8. link_text (which is the text of the link, and defaults to ‘Donate Now’).

Next, on line 33 we set an empty string for the $donate_link variable. The next section (line 35) in conjunction with this empty string, determines whether a “Donate Now” link is displayed at all:

if ( $atts['link'] != false ) {
    $donate_link = ' ' . $atts['link_text'] . '';
 }

If the shortcode doesn’t declare a `link`, an empty string is passed, and no Donate Now link is displayed.

The if() statement on line 33 targeting the `form_id` attribute makes sure that a form ID has been passed, and if so, it redeclares the $total variable as the total earnings for just that Form. Note that earnings for a single form are saved as post_meta for that form’s post and targeted with get_post_meta().

Next, the if() statement on line 43 targeting the multi_id attribute checks to see if that attribute has been declared in the shortcode. If it has, it resets the $total variable to zero, and then adds up the earnings from all declared Forms supplied by that parameter (by splitting up the array of form IDs and then looping through all of them and adding up the _give_form_earnings from each one). Since the check for multi_id comes after the check for form_id you should note that anything (numerical) entered as an attribute to multi_id will override anything entered into form_id.

Then, using all of that data, we build our Custom Nag using the $custom_nag variable on line 52. Within that, we made styling easy by giving the entire output a class of my-custom-nag, and within that gave spans classes of

• my-give-currency (targets both instances of the currency symbol)
• my-give-raised (only targets the raised amount)
• my-give-amount (targets both raised and total amounts),
• my-give-total (only targets the total amount)

The we return the Custom Nag, close the function, and call it using add_shortcode() on line 57.

Here’s the training guide for teaching Bob how to use this shortcode:

• [givetotal total_goal="10,000" link="http://example.com"] displays “So far, we have raised $0 toward our goal of $10,000! Donate now” (where “0” will be replaced with total earnings from all forms, and “Donate Now” is linked to http://example.com)
• [givetotal form_id="34" total_goal="10,000"] will display earnings for just form with an ID of 34, with no “Donate Now” link.
• [givetotal total_goal= "5,000" multi_id="34,114,141"] will display earnings for the three forms with IDs 34, 114, and 141, with no Donate Now link. Note that “multi_id” will override “form_id”, so don’t use both.

Here’s a sample with what the output looks like with a little CSS-love.
Shortcode:

[givetotal total_goal="9,000" message_before="Hey! We've raised " 
message_between=" of the " message_after=" we are trying to raise for this campaign!" 
link="http://example.com" link_text="Help Us Reach Our Goal." form_id="245"]

Output:

Armed with this shortcode, you can now sit back, and allow guys like Bob to feel like a rockstar for being able to add dynamic content to the site!

What Would You Do with a Custom Shortcode?

Armed with this primer into building Give shortcodes, now the floor is yours! What shortcodes do you plan to build? Our Give Snippet Library on GitHub is open for pull requests!

As always, let’s continue Democratizing Generosity!