Where to Place Code When Developing Apps

If you are building a full web app—basically one WordPress installation—you will have full access to the site and what themes and plugins are installed. Your code could go anywhere. Even so, you should follow some thought process when deciding whether a particular feature should be coded as a module of your app’s plugin or theme or as a separate plugin. The main benefactor of your good planning at this step will be your developers (maybe just you). Properly organizing your code is going to make it easier for you to maintain your app and develop it further.

When building apps, we try to use the following guidelines:

• Use one main plugin to store the core app code, and one theme to manage the frontend code.

• Any modular functionality that could be useful on other projects or potentially replaced by another plugin should be coded as a separate plugin.

• Never hack the core!¹

So what is core app code and what is frontend code? Again our pseudo-MVC framework looks like this:

Plugins = models

All of your code-defining data structures, business logic, and Ajax services should go into the core plugin. Things like definitions for CPTs and taxonomies, form processing, and class wrappers for the Post and User classes should also go into your core plugin.

Themes = views

All of your templating code and frontend logic should go in your theme. The frame of your website, header, footer, menu, and sidebars should be coded in your theme. Simple logic like if(is_user_logged_in()) { //show menu } else { //show login } should go into your theme.

One thing to consider when deciding where to code features is your development team. If you have a designer and programmer, you should put things the designer will be concerned with in the theme, and things that concern the programmer in the core plugin. Even if you have to finagle a little bit, clearly separating things like that will make it easier for your developers to find what they are looking for.

When Developing Plugins

If you are building a plugin to be used on other websites or modular features that can be used across projects, it makes sense to keep your code within one plugin. In these cases, you can store template files within your plugin to handle the UI components. It is common practice to allow these files to be overwritten by the active WordPress theme, which will be covered later in this chapter.

Where to Place Code When Developing Themes

Similarly, if you are developing a theme that will be distributed, and that relies on CPTs or other customization that would typically be coded in a plugin, it might make sense to instead include that within your theme. If your users must activate a plugin before your theme works at all, you might as well move the plugin code into your theme. If your theme makes large underlying changes to WordPress, consider putting that plugin-like code into a parent theme and putting your design-related code into a child theme. That way if your users want to change their site’s design without losing the other functionality provided by a theme, they can do so more easily.

On the other hand, if the code you are about to add to your theme is not crucial to the theme’s workings or there are other plugins that could be used as alternatives for your code, you should move that code into a plugin and distribute your theme as a bundle that includes the themes and recommended plugins. As an example, many premium themes add SEO-related fields to the edit post page to manage page titles, meta descriptions, and meta keywords. This makes sense, since these SEO-related fields represent a kind of view that is seen by Google and other web crawlers. However, there are a few really popular plugins that do this same functionality, and it’s hard to argue that your theme wouldn’t work without the SEO functionality installed. We would recommend theme developers put their SEO functionality into plugins or otherwise make it easy to disable so other plugins can be used.

In the end, the decision as to where to put what code and how to package things should be based on your users, both end users as well as the developers who will use your themes and plugins. Part of the beauty of WordPress is its flexibility in terms of how you can go about customizing it. There are no strict rules. Consider everything you read about this topic (including from us) as guidelines. If moving code from a plugin file to a theme file makes it easier to work with, do it.

Sample Page Template

Example 4-1 is a pared-down version of a contact form template that you can drop into your theme’s folder.

<?php
/*
Template Name: Page - Contact Form
*/

//get values possibly submitted by form
$email = sanitize_email( $_POST['email'] );
$cname = sanitize_text_field( $_POST['cname'] );
$phone = sanitize_text_field( $_POST['phone'] );
$message = sanitize_text_field( $_POST['message'] );
$sendemail = !empty( $_POST['sendemail'] );

// form submitted?
if ( !empty( $sendemail )
    && !empty( $cname )
	&& !empty( $email )
	&& empty( $lname ) ) {

	$mailto = get_bloginfo( 'admin_email' );
	$mailsubj = "Contact Form Submission from " . get_bloginfo( 'name' );
	$mailhead = "From: " . $cname . " <" . $email . ">
";
	$mailbody = "Name: " . $cname . "

";
	$mailbody .= "Email: $email

";
	$mailbody .= "Phone: $phone

";
	$mailbody .= "Message:
" . $message;

	// send email to us
	wp_mail( $mailto, $mailsubj, $mailbody, $mailhead );

	// set message for this page and clear vars
	$msg = "Your message has been sent.";

	$email = "";
	$cname = "";
	$phone = "";
	$message = "";
}
elseif ( !empty( $sendemail ) && !is_email( $email ) )
	$msg = "Please enter a valid email address.";
elseif ( !empty( $lname ) )
	$msg = "Are you a spammer?";
elseif ( !empty( $sendemail ) && empty( $cname ) )
	$msg = "Please enter your name.";
elseif ( !empty( $sendemail ) && !empty( $cname ) && empty( $email ) )
	$msg = "Please enter your email address.";

// get the header
get_header();
?>
<div id="wrapper">
 <div id="content">
 <?php if ( have_posts() ) : while ( have_posts() ) : the_post(); ?>
  <h1><?php the_title(); ?></h1>
  <?php if ( !empty( $msg ) ) { ?>
   <div class="message"><?php echo $msg?></div>
  <?php } ?>
  <form class="general" action="<?php the_permalink(); ?>" method="post">
   <div class="form-row">
	<label for="cname">Name</label>
	<input type="text" name="cname" value="<?php echo esc_attr($cname);?>"/>
	<small class="red">* Required</small>
   </div>
   <div class="hidden">
	<label for="lname">Last Name</label>
	<input type="text" name="lname" value="<?php echo esc_attr($lname);?>"/>
	<small class="red">LEAVE THIS FIELD BLANK</small>
   </div>
   <div class="form-row">
	<label for="email">Email</label>
	<input type="text" name="email" value="<?php echo esc_attr($email);?>"/>
	<small class="red">* Required</small>
   </div>
   <div class="form-row">
	<label for="phone">Phone</label>
	<input type="text" name="phone" value="<?php echo esc_attr($phone);?>"/>
   </div>
   <div class="form-row">
	<label for="message">Question or Comment</label>
	<textarea class="textarea" id="message" name="message" rows="4" cols="55">
		<?php echo esc_textarea( $message )?>
	</textarea>
   </div>

   <div class="form-row">
	<label for="sendemail">&nbsp;</label>
	<input type="submit" id="sendemail" name="sendemail" value="Submit"/>
   </div>
  </form>
 <?php endwhile; endif; ?>
 </div>
</div>
<?php
// get the footer
get_footer();
?>

WordPress will scan all of the .php files in your active theme’s folder and subfolders (and the parent theme’s folder and subfolders) for templates. Any files found with a comment that includes the phrase Template Name: in it will then be made available as a template.

The template is loaded after the WordPress init and wp actions have already fired. The theme header and the wp_head action will not load until you call get_header() in your template. So you can use the top of your template file to process form input and potentially redirect before any headers are sent to the page.

Your template file will need to include the same HTML markup as your theme’s page.php or single-post template. In the preceding example, we include a wrapper <div> and content <div> around the content of the contact form.

The preceding code also uses the sanitize_text_field() and sanitize_email() functions to clean up values submitted by the form. Similarly, it uses the esc_attr() and esc_textarea() functions to prevent cross-site scripting attacks. These functions are covered more in Chapter 8.

The preceding contact form also incorporates a “honey pot.” A field called lname would be hidden using CSS, so normal users would not see this field and thus leave it blank when submitting the form. Bots looking to take advantage of your contact form to send you spam will see the lname field and will put some value into it. The code that processes the form checks to make sure that the lname field is blank before then sending out the email. Like as a honey pot draws in insects, the hidden lname field draws spammers into it so you don’t end up sending email on their behalf.

Using Hooks to Copy Templates

If you’d rather not change multiple template files when you update the ID or class names of your wrapper <div>s, you can create a template that uses the the_content filter or another action specific to your theme to place content into the main content area of your page. Then you can load another template file, like the core page.php template, which will include calls to load your site’s frame and default layout. Example 4-2 shows how to create a page template that loads the page.php template and adds further content below it on certain pages.

<?php
/*
    Template Name: Hooking Template Example
*/

//use the default page template
require_once(dirname(__FILE__) . "/page.php");

//now add content using a function called during the the_content hook
function template_content($content)
{
    //get the current post in this loop
    global $post;

    //get the post object for the current page
    $queried_object = get_queried_object();

    //we don't want to filter posts that aren't the main post
    if(empty($queried_object) || $queried_object->ID != $post->ID)
        return $content;

    //capture output
    ob_start();
    ?>
    <p>This content will show up under the page content.</p>
    <?php
    $temp_content = ob_get_contents();
    ob_end_clean();

    //append and return template content
    return $content . $temp_content;
}
add_action("the_content", "template_content");

In this previous example, we do a little trick to check the current $post against the $queried_object. Typically, the global $post will be the main post of the page you have navigated to. However, other loops on your page will temporarily set the global $post to whatever post they are dealing with at the time. For example, if your template uses a WordPress menu, that is really a loop through posts of type menu. Many sidebars and footer sections will loop through other sets of posts.

The get_queried_object() function returns the main post object for the current page. The function returns a different but appropriate object if you are on a term or author page. The function returns null on archive pages. Because the previous example is a page template that will be loaded only on single page views, calling get_queried_object() there will always return a $post object for the current page.

You can also insert your own hook into your page.php and other core templates to do something similar. Just add something like do_action('my_template_hook'); at the point in your page template where you’d like to add in extra content.

When Should You Use a Theme Template?

In Chapter 3, we covered how to use shortcodes to create pages for your plugins. The shortcodes are useful because they allow you to add CMS-managed content above and below the shortcode in the post content field and to keep your code organized within your plugin. So, if you are distributing a plugin and need that page template to go along with it, you should use the shortcode method to generate your page.

Similarly, if you are distributing a theme by itself, you’ll need to include any templates needed for the theme within the theme folder. You could include code for shortcode-based templates within your theme, but templates are a more standard way of templating a page.

And finally, if your template needs to alter the HTML of your default page layouts, you will want to use a template file inside of your theme. Example 4-2 piggybacks on the page.php template to avoid having to rewrite the wrapping HTML. But if the whole point of the template is to rewrite the wrapping HTML (e.g., with a landing page template where you want to hide the default header, footer, and menu), you definitely need to use a template.

Using locate_template in Your Plugins

A common design pattern used in plugins is to include templates in your plugin folder and allow users to override those templates by adding their own versions to the active theme. For example, in SchoolPress, teachers can invite students to their class. The invite form is stored in a template within the plugin:

//schoolpress/templates/invite-students.php
?>
<p>Enter</p>
<form action="" method="post">
	<label for="email">Email:</label>
<input type="text" id="email" name="email" value="" />
	<input type="submit" name="invite" value="Invite Student" />
</form>

SchoolPress is envisioned as an SaaS application, but we also plan to release a plugin version for others to use on their own sites. Users of the plugin may want to override the default template without editing the core plugin, since edits to the core plugin would be overwritten when the plugin was upgraded.

To enable our plugin users to override the invite template, we use code like the following when including the template file:

//schoolpress/shortcodes/invite-students.php
function sp_invite_students_shortcode($atts, $content=null, $code="")
{
	//start output buffering
  ob_start();

	//look for an invite-students template part in the active theme
	$template = locate_template('schoolpress/templates/invite-students.php');

	//if not found, use the default
	if(empty($template))
		$template = dirname(__FILE__) .
            '/../templates/invite-students.php';

	//load the template
	load_template($template);

	//get content from buffer and output it
	$temp_content = ob_get_contents();
	ob_end_clean();
	return $temp_content;
}
add_shortcode('invite-students', 'sp_invite_students_shortcode');

This code uses our shortcode template from Chapter 3. But instead of embedding the HTML into the shortcode function, we load it from a template file. We first use locate_template() to search for the template in the active child and parent themes. Then, if no file is found, we set $template to the path of the default template bundled with the plugin. The template is loaded using load_template().

Versioning Your Theme’s CSS Files

It’s good practice to set a version for your CSS files when loading them through wp_enqueue_style(). This way, if you update your CSS, you can also update the version, and avoid having site users see a seemingly broken site that uses a version of the stylesheet cached by the browser.

When WordPress enqueues your theme’s style.css file for you, it uses the overall WordPress version when loading the stylesheet. The line output in your site’s head tag will look like this:

<link rel='stylesheet'
	id='twentynineteen-style-css'
	href='.../wp-content/themes/twentynineteen/style.css?ver=1.4'
	type='text/css'
	media='all' />

Updates to the stylesheet, your app’s version number, or even the version number set in the style.css comment won’t update the version added to the stylesheet when enqueued. It will always match the WordPress version number.

One solution is to remove all CSS from your style.css file into other CSS files in your theme and load those CSS files through wp_enqueue_style() calls in the theme’s functions.php file. It would look like this for style.css:

/*
   Theme Name: SchoolPress
   Version: 1.0

   That's it! All CSS can be found in the "css" folder of the theme.
*/

and like this for functions.php:

<?php
define( 'SCHOOLPRESS_VERSION', '1.0' );
function sp_enqueue_theme_styles() {
	if ( !is_admin() ) {
		wp_enqueue_style( 'schoolpress-theme',
			get_stylesheet_directory_uri() . '/css/main.css',
			NULL,
			SCHOOLPRESS_VERSION
		);
	}
}
add_action( 'init', 'sp_enqueue_theme_styles' );
?>

A constant like SCHOOLPRESS_VERSION would typically be defined in our main plugin file, but it’s included here for clarity. The preceding code loads our new /css/main.css file with the main app version appended so new versions of the app won’t conflict with browser-cached stylesheets.

There is another way to change the version of the main style.css file without moving it to another file entirely. We use the wp_default_styles filter. This filter passes an object containing the default values used when a stylesheet is enqeued. One of those values is the default_version, which can be changed like so:

define('SCHOOLPRESS_VERSION', '1.0');
function sp_wp_default_styles($styles)
{
    //use release version for stylesheets
	$styles->default_version = SCHOOLPRESS_VERSION;
}
add_action("wp_default_styles", "sp_wp_default_styles");

Now our main stylesheet will be loaded using the SchoolPress app version instead of the main WordPress version. We can keep our CSS in style.css if we want to, though it’s often a good idea to move at least some parts of the CSS into separate files in a “css” folder of your theme.

WordPress Theme Frameworks

WordPress theme frameworks are themes that are meant to be used as parent themes or starter themes to jump-start your frontend development. Theme frameworks typically include basic styles and layouts for blog posts, as well as archives, pages, sidebars, and menus. They are of varying weights, and some include CSS classes, shortcodes, and other handy bits of code to help you create new layouts and add UI elements to your pages. All frameworks will likely save you a lot of time.

There are two reasons to choose one theme framework over another: you either choose a child theme that visually looks very close to your vision for your app, or you choose a framework coded in a way that feels right when you work with it.

Non-WordPress Theme Frameworks

In addition to WordPress theme frameworks, there are also application UI frameworks that provide markup, stylesheets, and images for common UI patterns and elements. Some popular UI frameworks include Twitter’s Bootstrap and Zurb’s Foundation.

Incorporating a UI framework into your theme can be as easy as copying a few files into the theme folder and enqueueing the stylesheets and JavaScript. This gives you easy access to styled UI elements like buttons, tabs, pagination, breadcrumbs, labels, alerts, and progress bars.

Next, we’ll cover how to add Bootstrap assets into a Memberlite child theme, but the same process should work for other combinations of WordPress themes and UI frameworks.

Navigation Menus

Since WordPress version 3.0, the standard method for adding navigation menus to themes involved registering the menu in the theme’s code, designating where in the theme the menu will appear, and then managing the menu through the WordPress dashboard.

The main benefit to using WordPress’s built-in menu functionality is that end users can control the content of their menus using the dashboard GUI. Even if you are a developer with full control over your app, it is still a good idea to use the built-in menus in WordPress since you may have stakeholders who would want to manage menus or you may want to distribute your theme to others in the future. The WordPress navigation menus are also very easy to reposition and can take advantage of other code using menu-related hooks or CSS styles.

To register a new navigational menu, use the register_nav_menu( $location, $description ) function. The $location parameter is a unique slug used to identify the menu. The $description parameter is a longer title for the menu shown in the drop-down in my menu tool in the dashboard:

register_nav_menu('main', 'Main Menu');

You can also register many menus at once using the register_nav_menus() (with an s) variant. This function accepts an array of locations in which the keys are the $location slugs and the values are the $description titles:

register_nav_menus(array(
	'main' => 'Main',
	'logged-in' => 'Logged-In'
));

To place a navigational menu into your theme, use the wp_nav_menu() function:

wp_nav_menu( array('theme_location' => 'main' ));

The theme_location parameter should be set to the $location set with register_nav_menu(). The wp_nav_menu() function can take many other parameters to change the behavior and markup of the menu. This WordPress Codex page on navigation menus is a good resource as the various parameters to the wp_nav_menu() function and other ways to customize menus. We cover some of our favorite recipes in the following sections.

Dynamic Menus

There are two main methods to make your WordPress menus dynamic so that different menu items show up on different pages or under different circumstances. The first is to set up two menus and load a different menu depending on the case. Here is a code example from the Codex showing how to display a different menu to logged-in users and logged-out users:

if ( is_user_logged_in() ) {
     wp_nav_menu( array( 'theme_location' => 'logged-in-menu' ) );
} else {
     wp_nav_menu( array( 'theme_location' => 'logged-out-menu' ) );
}

The other way to make your menu dynamic is to use the nav_menu_css_class filter to add extra CSS classes to specific menu items. Then you can use CSS to hide/show certain menu items based on their CSS class.

Say you want to remove a login link from a menu when you’re on the login page.³ You could use code like this:

function remove_login_link($classes, $item)
{
	if(is_page('login') && $item->title == 'Login')
    $classes[] = 'hide';	//hide this item

  return $classes;
}
add_filter('nav_menu_css_class', 'sp_nav_menu_css_class', 10, 2);

You can also customize the markup of your menus by using Custom Walker classes (see Chapter 7).