Theming the single Give page is very straight forward. This article will give you an overview of the easiest way to start customizing your single Give page in just a few steps.

While Give does respect the WordPress Template hierarchy, there’s an even easier way to start customizing your single Give page. Simply copy your single.php or page.php file from your theme and create give.php. Here’s what the folder structure would then look like:

/wp-content/themes/your-theme/give.php

With give.php in place, all your single Give Forms will use that file instead of the single template inside the Give plugin.

But now that you have that in place, what can you do with it? Well, pretty much anything, but let’s go one step at a time first.

While Give does respect the WordPress Template Hierarchy, it's easiest to start customizing your single Give pages by just adding give.php to your theme.

Anatomy of the Give Single Page

The Give single page is made up of 2 main elements:

  • The Give Sidebar
  • The Give summary

Each of those elements controls several other important parts of a Give single page. Here’s the breakdown:

The Give Summary

  • The form title
  • The form content (if you choose to add content)
  • The donation form itself

The Give Sidebar

  • The Featured image
  • The dedicated Give sidebar which you can add widgets to

Native WordPress Elements

Besides these main elements, a Give form is very similar to a standard WordPress post in that it also supports common elements that you may already be familiar with, like:

  • the_title() is the Form title
  • the_post_thumbnail() is the Form’s featured image
  • the_excerpt() is the Form’s excerpt

One way in which a Give Form is different from a standard post is that you cannot get the content of a Give form with the_content().

A Sample give.php Template File

It’s difficult to really grasp how to implement these things by simply reading about them. The best way to learn anything is hands-on. That’s why we’ve published “Give 2015“. It’s a Twenty Fifteen child theme that illustrates exactly how you can theme Give. Feel free to check out the whole child theme and play with it. But let’s look directly at the give.php file in Give 2015.

Give 2015's give.php file

<?php
/**
 * The template for displaying all single Give Donation Forms
 *
 */

get_header(); ?>

	<div id="primary" class="content-area">
		<main id="main" class="site-main" role="main">

		<?php
		do_action( 'give_before_main_content' );

		// Start the loop.
		while ( have_posts() ) : the_post();

			give_get_template_part( 'single-give-form/content', 'single-give-form' );

		// End the loop.
		endwhile;

		do_action( 'give_after_main_content' );
		?>

		</main><!-- .site-main -->
	</div><!-- .content-area -->

<?php get_footer(); ?>

As you can see, all it does is use the wrapper div’s from Twenty Fifteen’s page.php file and then calls a template part for the content. But look closely at this line:

give_get_template_part( 'single-give-form/content', 'single-give-form' );

That line has two things to pay attention to:

  1. The give_get_template_part() function
  2. And the folder structure of the template part being called

The give_get_template_part() function is made to call any template part that Give offers. It also respects any template part that you’ve added into your theme as an override. In this case, it’s the `content-single-give-form.php` file that is located in our Give 2015 child theme like this:

themes/give-2015/give/single-give-form/content-single-give-form.php

That’s where a lot of the magic of this child theme is for re-arranging the elements, so let’s dig into that next.

The content-single-give-form.php template file

 

Give 2015's content-single-give-form.php template file

<?php

do_action( 'give_before_single_form' );

if ( has_post_thumbnail() ) {

	$image = wp_get_attachment_image_src( get_post_thumbnail_id( $post->ID ), 'donate-header' );
	$headerbkgrnd = "url('" . $image[0] . "');";
} else {
	$headerbkgrnd = '#777;';
}

?>

<h1 itemprop="name" class="give-form-title entry-title" style="background: <?php echo $headerbkgrnd; ?>"><?php the_title(); ?></h1>

<div id="give-form-<?php the_ID(); ?>-content" <?php post_class(); ?>>
	<div class="<?php echo apply_filters( 'give_forms_single_summary_classes', 'summary entry-summary' ); ?>">

		<?php give_get_donation_form( $args = array() ); ?>

	</div>
	<!-- .summary -->

	<?php	do_action( 'give_after_single_form_summary' );	?>

</div><!-- #give-form-<?php the_ID(); ?> -->

<?php do_action( 'give_after_single_form' ); ?>

If you view this file on Github you’ll notice that there’s a few more details in there and lots of inline documentation for your reference. The code above is stripped down to the bare minimum of what is necessary for this template part to display the Give form page correctly.

Let’s go through the major elements of this page one by one

Before and After Actions (Optional)

You’ll notice several actions that reference “before” or “after” in them. These are purely optional. They are hooks that are available specifically for plugins (or premium Addons) to use to add custom information or functionality. So, if you are doing custom theming like this and notice that a particular Addon isn’t behaving with your custom theme, but DOES with Twenty Fifteen you might want to review and make sure you’re including these actions.

The Featured Image

You’ll see that this looks similar to many theme’s implementation of a featured image. That’s because it is just like that. In this case, we’re getting the featured image URL so it can be applied to the title background.

The Title

Just like a normal post, your Give form has a title and uses the WordPress Core function `the_title()` to output it.

Unique Classes and IDs

The Give fields and even some of the javascript depends a lot on the wrapper div classes and IDs. Here’s several pieces to pay close attention to:

  • id="give-form-<?php the_ID(); ?>-content" — this is an important ID that you really want to make sure is present in your wrapper div.
  • <?php post_class(); ?> — this is a WordPress Core function that Give leverages and should also be present in your wrapper div.
  • <div class="<?php echo apply_filters( 'give_forms_single_summary_classes', 'summary entry-summary' ); ?>"> — this is another important wrapper div which the Give form relies on these particular classes very much.

Notice that the last item is a filter. This is covered in other documentation, but keep in mind that you can manipulate the summary classes with this filter.

Get the form already!

Finally we need to actually output the donation form onto the page. In the native Give template file we use this action to output the form:

do_action( 'give_single_form_summary' );

That action outputs both the Form title and the form itself. Because we wanted to handle the title a bit differently we don’t want to use that action. Instead, we just call this function to get the form by itself:

give_get_donation_form( $args = array() );

Note that this will include all of the following:

  • The Goal progress bar if you’ve set a Goal for your form
  • The content either before or after the form if you’ve enabled content and entered it
  • The Give donation form itself.

Tips for Going Deeper

That’s the general overview for the Give single page. It’s fairly straight-forward if you are familiar with theming other plugins like bbPress, WooCommerce, or Easy Digital Downloads.

If you want to find out more ways to customize this page we’d encourage you to dig into the /templates/ folder inside the GIve plugin and start dropping those files into your theme and experimenting (in a safe local or staging environment!). Also look into all the functions, filters, and actions available to you in these files:

  • /includes/forms/functions.php
  • /includes/forms/template.php
  • /includes/template-functions.php