Theming the GiveWP Archive Page

GiveWP uses the WordPress Template Hierarchy to allow you to have Archives of all of your GiveWP forms. This article describes how to interact with and customize the GiveWP Archive page.

Archives in WordPress refer to pages which display more than one post. Archives are more generic, and to give you an idea of _types_ of archives, by default you have author archives (displaying posts from a selected author) date archives (displaying posts from a selected date), tag archives (displaying posts from a selected tag), and category archives (displaying posts from a selected category).

In addition to those default archives, you also have custom taxonomy archives and custom post type archives, for any custom taxonomies and/or custom post types defined in your WordPress install.

Your GiveWP donation forms are a custom post type, so a page that displays multiple donations form is what we call a GiveWP donation form archive, or the shorter “GiveWP archive.”

Out of the box, GiveWP inherits the vast majority of its visual elements from your theme (or child theme) but if you are looking to visually extend your GiveWP archives, you’ll want to do it in a way that doesn’t style _all_ of the archives on your site. This document will walk you through the process, pointing out some WordPress best practices along the way.

Also, throughout any documentation on theming, you’ll see us use “(child) theme” in place of “theme,” as a helpful reminder that it is a WordPress best practice to always do any theme customizations in the form of a child theme, to avoid having those customizations overwritten by theme updates. You can technically make all of the adjustments in the theme, it’s just not advisable. Read more about Child themes here: https://codex.wordpress.org/Child_Themes

Enabling Archives in GiveWP

First, before you attempt to create custom GiveWP archives, you need to ensure that GiveWP archives are enabled in your GiveWP settings. Navigate to Donations > Settings > Default Options and ensure that the box next to “Disable Form Archives” is NOT checked. This is the default setting, so unless you’ve changed it, you should be OK.

Understanding the Template Hierarchy

The Theme Developer Handbook’s page on the WordPress Template Hierarchy does a great job of explaining this concept in detail, and it’s worth reading the entire thing, but the most pertinent part of the discussion for this particular document is how it relates to archives.

For that, following the top-left block in this diagram is helpful in understanding: https://wphierarchy.com/

When an archive page is served in WordPress, first WordPress determines from the requesting URL what type of archive it is, and based on that information, begins running down the archive template files in the (child) theme folder. So, for a GiveWP archive, WordPress will look first for archive-give_forms.php before defaulting back to archive.php and then if it can find neither, falling all the way back to index.php.

So, the first step in theming your GiveWP archive is to have a file in your (child) theme’s folder named archive-give_forms.php.

Here’s a sample to start from.

Let’s walk through the code there to get an idea of what the file is doing, and to give you some jumping-off points to create your own stunning GiveWP archives.

To clarify: you can start from any file, and the closer your php file sticks to the styling conventions of the parent theme, the better. Our sample file here is a simplification designed to work with the twenty sixteen theme.

Understanding the Loop

The Loop is what what WordPress uses to display posts on a given page. The Developer handbook page on the Loop is helpful here to gain a basic understanding. Let’s walk through what the loop does in our specific context:

When you call the loop with no args, WordPress will pull all posts, not just our Custom Post Type of “give_forms,” so you see on line 23 that we add in some arguments as an array of what type of posts you want, before calling for the Loop on line 28.

That way, you have already specified what type of posts you want WordPress to display. The if() statement on line 30 makes it more simple to display something in the event that the loop comes up empty. Check the bottom of the file for what WordPress will output in that case (line 76 and following).

A Basic Archive Example

So, back to line line 30. Assuming you have one or more donation forms live on your site, the next thing we want to do is give the archive page a heading that is displayed. For our sample file, we went with

<h1 class="my-give-archive-title">All The Ways You Can Support Us</h1>
<hr/>

Which outputs a heading styled like the rest of the <h1> headings in your theme, and a horizontal rule (line) also styled as your theme declares. More on styling later.

Then we get to the part of the loop that gives it its name, looping through the database to get all of the posts that match our post_type of “give_forms.” Line 33 of the file is doing all of that work.

For each of those individual form sections, we want to be able to style them individually, so we start with a div and give it a class of “my-give-archive-form.” You can feel free to use whatever class name you’d like, there—just make sure that you choose something unique so that later when you are styling, you can select by class without styling other elements of the site.

Then, we select which pieces of content we want from each post to show up on the archive page. In our sample, we picked the title, the featured image, the content, and the goal. To ensure that the content and goals don’t output empty divs when dealing with donation forms that don’t have one or the other, we wrapped each of those in if() statements.

One thing to note, if you chose the give_get_template_part( ‘single-give-form/featured-image’); method of calling the featured image, you need to ensure that each form on your site has a featured image, or you’ll display the placeholder images for the form. Also, this method of calling the featured image obeys the size that you’ve set in Donations > Settings > Default Options (tab).

Once the loop has done its work, the only remaining things to do are call the sidebar and footer, and you have created a custom archive of GiveWP donation forms!

Adding Hooks for customizing your Archives

What if you wanted to add some custom content on your archive page, without having to go back and mess with this file? To do that, you may have noticed that we’ve added hooks throughout this file using lines with do_action() functions. These provide ways for you to harness the power of WordPress hooks.

Want to add a box above the loop? Write a function in a must-use plugin, or your functions.php file that hooks into “my-give-before-archive-loop” (line 36) and it’ll display before the loop on your archive page.

Try this in your theme’s functions.php to see what we mean:

function my_give_test_the_hook() { 
    echo 'This text will show up before the loop!'; 
} 
add_action('my-give-before-archive-loop', 'my_give_test_the_hook');

Similarly, we’ve added hooks before and after each form in the loop (lines 42 and 73) for displaying content in those two places. This allows you or others to extend the functionality of this page, without having to hack this file.

Questions?

We’d love to clarify. Also, our GiveWP snippet library accepts PRs if you come up with some good archive templates for your theme that you’d like to share! Happy theming!