Skip to content

Tips For Writing Custom Code For Charitable

One reason Charitable is one of the best WordPress plugins to run campaigns and accept donations is it’s flexibility and ability to allow others to customize various key aspects of the experience – including emails, campaign details, and the donation form. Some of this flexibility exists in the “hooks and filters” that Charitable has in it’s code that are available to WordPress developers. Through these, a developer can customize a site to:

— Display a custom field on the donation field via the Donations Field API.
— Add new email tags or modify existing ones with the Email Fields API.
— Customizations to addons such as the Ambassador addon and the Annual Receipts addon.

Code for a WordPress plugin can be written in a number of ways and in different places: some code can be placed in the “functions.php” file of the active WordPress theme, some are written into a plugin (that can be activated and deactivated even if the user keeps the same theme), and (what is becoming increasing popular) code can be hosted in a code snippets plugin.

No matter where the code lives, there are best practices that WordPress developers and coders should be using to ensure the website it’s running in stays secure and doesn’t fall to errors. The following isn’t a complete nor in depth guide, but general reminders for those writing code OR accepting code from developers to insert into their website – especially if that code relies on a third party plugin (like Charitable). 

Plugin File Preferred

If possible try to place custom code in it’s OWN WordPress plugin. This makes it easier to keep the code in place if you switch your WordPress theme and it also allows you to easily turn the plugin containing the customizations on/off for debugging purposes. There are many posts and tutorials on the web about creating a simple WordPress plugin such as this one.

Don’t Assume, Always Check

It’s important for any custom code NOT TO ASSUME CHARITABLE IS ACTIVATED AND RUNNING ON YOUR WEBSITE. Why? Because if it attempts to call a function in Charitable’s core code – and the code isn’t there – an error can occur… an error that could bring down your website! Sometimes WordPress is able to put your site in “Recovery Mode” and send the site administrator an email to notify them about this error, but this isn’t always the case. Therefore, ANY code written for Charitable – regardless of it’s purpose or where the code is located – should “check” to make sure Charitable is activated and/or the function they are attempting to call exists.

Notice our first (bad!) example:

👎🏻 BAD EXAMPLE:

// Bad Example :-( Of Hooking Into Charitable

function charitable_add_donation_gateway_email_tag() {
    charitable()->donation_fields()->get_field( 'gateway_label' )->email_tag = true;
}
add_action( 'init', 'charitable_add_donation_gateway_email_tag' );

The purpose of this block of code is to make the “gateway label” something that can be added as a dynamic tag into Charitable emails. The developer above is “hooking” the function that does this WordPress’s “init” which is run every time a page is loaded on the website – no matter if it’s in the admin or the front end. Notice the function uses “charitable()”… but if this doesn’t exist PHP will throw a “fatal error” – and since the above code is loading on ANY and EVERY page load, the entire site will most likely crash without ability to log in as an admin, etc.

Again, it’s a good practice to never assume a function exists if that function is part of a plugin or theme (in other words if it’s not a part of WordPress core). Assuming the “charitable()” class exists means assuming the Charitable plugin will ALWAYS be there – but if the plugin is deactivated (by a human or by another plugin) or if the plugin is being updated… the function will not be found, and a (possible “fatal”) error would be encountered. Here’s the same function but with a simple addition:

👍🏻 GOOD EXAMPLE:

// Good Example :-) Of Hooking Into Charitable
// Checking To See If The Class Exists!

function charitable_add_donation_gateway_email_tag() {
    if ( class_exists('charitable') ) : // check for class
       charitable()->donation_fields()->get_field( 'gateway_label' )->email_tag = true;
    endif;
}
add_action( 'init', 'mysite_charitable_add_donation_gateway_email_tag' );

Notice the “if” statement that checks if the class of “charitable” exists – this is a way in PHP to safely check if the class exists (in this case it will only if Charitable is actively running on the website). If it doesn’t exist, then the code isn’t run and everyone is safe. It’s common for PHP developers to make checks like class_exists and function_exists for quick ways to ensure the code they are about to run won’t run into serious errors because something they are assuming exists doesn’t exist.

Use Unique Names For Functions

As noted in the above examples, never give your functions generic names like “update_email” because if another plugin uses that same name (current plugins or future ones you might install) then your website might suffer problems. When creating a function always start with “mywebsite_charitable_” (like the example above, replacing “mywebsite” with a reasonable length string of your website name) to ensure that you have likely created a custom name that isn’t repeated (you can also use the same “does this already exist logic” in the above step if you want to go the extra mile).

Enable WordPress Debugging and Debug Logs

For anything beyond a simple script, WordPress developers commonly like to document and log PHP warnings and errors to “catch” problems (especially if they aren’t apparently visible on the website). Charitable Support team recommends the base WP_DEBUG and WP_DEBUG_LOG functions as mentioned here in the WordPress documentation.

Using A Code Snippet Plugin?

Everything said above is applicable also to code inserted into code snippet plugins. If you have a problem with Charitable and know you are running custom code in a code snippet, you should be able to deactivate the code snippet plugin to see if this resolves the issue or helps you further troubleshoot.

Don’t Test On Production

Finally, it’s a good idea to test custom code on a staging or development environment and not live on your website. If you deactivate Charitable here as a test it’s a good “final” way to determine if your website might experience significant problems. This keeps your production environment safe and still able to accept donations. 

Remember that if you are unsure about the code you are adding to your theme, your own plugin, or code snippet plugin – consult with a developer. If you have some general questions feel free to reach out to our support team who will be happy to answer questions about any code you might be adding to your website to extend Charitable. We are here for you and to support you in extending your website to meet your needs!

We hope sharing these suggestions will give you the confidence and ensure your customizations to Charitable will continue to operate well for years to come.