Theming the Single GiveWP Page

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

While GiveWP does respect the WordPress Template hierarchy, there’s an even easier way to start customizing your single GiveWP 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 GiveWP Forms will use that file instead of the single template inside the GiveWP 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.

Anatomy of the GiveWP Single Page

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

• The GiveWP Sidebar
• The GiveWP summary

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

The GiveWP Summary

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

The GiveWP Sidebar

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

Native WordPress Elements

Besides these main elements, a GiveWP 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 GiveWP Form is different from a standard post is that you cannot get the content of a GiveWP 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. Let’s look directly at the give.php file in the sample GiveWP 2015.

	<div id="primary" class="content-area">
		

		

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

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 GiveWP 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 GiveWP 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

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

?>

<h1 itemprop="name" class="give-form-title entry-title" style="background: "></h1>

<div id="give-form--content" >
	<div class="">

		

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

	

</div><!-- #give-form- -->

The code above is stripped down to the bare minimum of what is necessary for this template part to display the GiveWP 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 GiveWP form has a title and uses the WordPress Core function `the_title()` to output it.

Unique Classes and IDs

The GiveWP 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 GiveWP 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 GiveWP 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 GiveWP 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 GiveWP donation form itself.

Tips for Going Deeper

That’s the general overview for the GiveWP 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 GiveWP 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