Using WordPress Plugins: Installing, Structure, Building Your Own Plugin

/adminpages/

Place the .php files for any dashboard page you add through your plugin in the /adminpages/ directory. For example, here is how you would add a dashboard page and load it out of your /adminpages/ directory:

<?php
// add a SchoolPress menu with reports page
function sp_admin_menu() {
    add_menu_page(
		'SchoolPress',
		'SchoolPress',
		'manage_options',
		'sp_reports',
		'sp_reports_page'
	);
}
add_action( 'admin_menu', 'sp_admin_menu' );

// function to load admin page
function sp_reports_page() {
	require_once dirname( __FILE__ ) . "/adminpages/reports.php";
}
?>

/classes/

Place PHP class definitions in the /classes/ directory. In general, each file in this directory should include just one class definition. The class files should have names like class.<ClassName>.php, where ClassName is the name given to the class.

/css/

Place CSS files used specifically for your plugin in the /css/ directory. Split your CSS into admin.css and frontend.css files depending on whether the CSS affects the WordPress dashboard or something on the frontend. For example, you can also place the CSS libraries needed to support an included JavaScript library in this folder.

Here is some code to enqueue the admin.css and frontend.css styles from the plugin’s CSS folder:

<?php
function sp_load_admin_styles() {
	wp_enqueue_style(
		'schoolpress-plugin-admin',
		plugins_url( 'css/admin.css', __FILE__ ),
		array(),
		SCHOOLPRESS_VERSION,
		'screen'
	);
}
add_action( 'admin_enqueue_scripts', 'sp_load_admin_styles' );

function sp_load_frontend_styles() {
    wp_enqueue_style(
        'schoolpress-plugin-frontend',
        plugins_url( 'css/frontend.css', __FILE__ ),
        array(),
        SCHOOLPRESS_VERSION,
        'screen'
    );
}
add_action( 'wp_enqueue_scripts', 'sp_load_frontend_styles' );
?>

The admin_enqueue_scripts hook should be used to enqueue scripts and styles meant for the administrator dashboard. The wp_enqueue_scripts hook should be used to enqueue scripts and styles meant for the frontend.

CSS that affects components of the WordPress dashboard should go into the admin.css file. CSS that affects the frontend of the site should go into frontend.css, but be careful when adding CSS rules to the frontend.css file. When adding frontend styles to your plugin files, ask yourself first whether the CSS rules you are writing should go into the app’s theme instead, since the majority of your frontend-style code should be handled by your theme.

The CSS that would go into the plugin’s CSS file are generally layout styles that would be appropriate no matter what theme was loaded. Imagine that your site had no theme or CSS loaded at all. What would be the bare minimum CSS needed to have the HTML generated by your plugin make sense? Expect the theme to build on and override that.

For example, your plugin’s frontend.css should never include styles for coloring. However, a style saying an avatar is 64 pixels wide and floated left could be appropriate.

/js/

Place any JavaScript files needed by your plugin in this folder. Again, you can split things into an admin.js and frontend.js file depending on where the JavaScript is needed.

You can also add to this folder third-party JavaScript libraries that you use. Generally, these should be added to a subfolder of the /js/ directory.

Here is some example code to load admin.js and frontend.js files from your plugin’s /js/ directory:

<?php
function sp_load_admin_scripts() {
	wp_enqueue_script(
		'schoolpress-plugin-admin',
		plugins_url( 'js/admin.js', __FILE__ ),
		array( 'jquery' ),
		SCHOOLPRESS_VERSION
	);
}
add_action( 'admin_enqueue_scripts', 'sp_load_admin_scripts' );

function sp_load_frontend_scripts() {
	wp_enqueue_script(
		'schoolpress-plugin-frontend',
		plugins_url( 'js/frontend.js', __FILE__ ),
		array( 'jquery' ),
		SCHOOLPRESS_VERSION
	);
}
add_action( 'wp_enqueue_scripts', 'sp_load_frontend_scripts' );
?>

As with stylesheets, it can be difficult to determine whether some bit of JavaScript should be included in the plugin’s JavaScript file or the theme’s JavaScript file. In general, JavaScript files that support the theme (e.g., slider effects and menu effects) should go in the theme, and JavaScript files that support the plugin (e.g., Ajax code) goes in the plugin. In practice, however, you will find your plugin using JavaScript defined in your theme, and vice versa.

/images/

Place any images needed by your plugin in the /images/ directory.

/includes/

The /includes/ directory is a kind of catchall for the .php files your plugin needs. The only .php file in your plugin’s root folder should be the main plugin file schoolpress.php. All other .php files should go in one of the other folders; if none are more appropriate, either make another folder or place it in the /includes/ folder.

It is standard procedure to add a functions.php, common.php, or helpers.php file to include any helper PHP code used by your plugin. This file should include any small scripts that don’t have a central role in the logic or functionality of your plugin but are needed to support it. Examples include functions to trim text, functions to generate random strings, or other framework-like functions that aren’t already available through a core WordPress function.

/includes/lib/

Place the third-party libraries needed for your app into the /includes/lib/ directory.

/pages/

Place any .php code related to frontend pages added by your plugin in the /pages/ directory. Frontend pages are typically added through shortcodes that you would embed into a standard WordPress page to show the content you want.

The following code snippet illustrates how to create a shortcode that can be placed on a WordPress page to generate a page from your plugin. The preheader here is a chunk of code to run before the wp_head() function loads, and thus before any HTML headers or code are sent to the browser. The shortcode function further down outputs HTML to the actual page at the place of the shortcode.

Place this code in /plugins/<your plugin folder>/pages/stub.php and then include it (typically using the require_once() function) from your main plugin file. Then, add the shortcode [sp_stub] to a page of your WordPress site:

<?php
// preheader
function sp_stub_preheader() {
	if ( !is_admin() ) {
		global $post, $current_user;
		if ( !empty( $post->post_content ) && strpos
		   ( $post->post_content, '[sp_stub]' ) !== false ) {
			/*
				Put your preheader code here.
			*/
		}
	}
}
add_action( 'wp', 'sp_stub_preheader', 1 );

// shortcode [sp_stub]
function sp_stub_shortcode() {
	ob_start();
	?>
	Place your HTML/etc code here.
	<?php
	$temp_content = ob_get_contents();
	ob_end_clean();
	return $temp_content;
}
add_shortcode( 'sp_stub', 'sp_stub_shortcode' );
?>

For the preheader code, we first check that the page is being loaded from outside the admin using !is_admin(); otherwise, this code might run when we’re editing the post in the dashboard. Then we look for the string [sp_stub] in the content of the $post global. This function is hooked to the wp hook, which runs after WordPress sets up the $post global for the current page, but before any headers or HTML are output.

The preheader code can be used to check permissions, process form submissions, or prep any code needed for the page. In an MVC model, this would be your model and/or controller code. Because this code is run before any headers are output, you can still safely redirect users to another page. For example, you can wp_redirect() them to the login or signup page if they don’t have access to view the page.

In the shortcode function, we use ob_start(), ob_get_contents(), and ob_end_clean(), which are PHP functions used to buffer output to a variable. Using this code means that the code between the preceding ?> and <?php tags is placed into the $temp_content variable instead of output at the time of processing (which would have it echoed out above the <html> tag of your site). This isn’t necessary: you could just define a $temp_content() function and use PHP to add to that string. Using output buffering allows us to code in a more template-like way, mixing HTML and PHP, which is easier to read.

/services/

Place any .php code for Ajax calls in the /services/ directory.

/scheduled/

Place any .php code that is related to cron jobs or code that is meant to be run at scheduled intervals here.

/schoolpress.php

This is the main plugin file. For small plugins, this may be the only file needed. For large plugins, the main plugin file will contain only include statements, constant definitions, and some comments about which other files contain the code you might be looking for.

The WordPress Loop

The great and powerful WordPress loop is what makes WordPress display its posts. Depending on what theme template file is being called on when navigating your website, WordPress queries the database and retrieves the posts that need to be returned to the end user and then loops through them.

Most correctly built WordPress themes usually have the following files that contain the WordPress loop:

• index.php

• archive.php

• category.php

• tag.php

• single.php

• page.php

If you open any of these files, they’ll contain code that may look something like this:

<?php
if ( have_posts() ) {
	while ( have_posts() ) {
		the_post();
		the_title( '<h2>', '</h2>' );
		the_content();
	}
} else {
	// show a message like sorry no posts!
}
?>

The have_posts() function checks to see whether there are posts that need to be looped, and if so, the while loop is initiated. The the_post() function called first in each iteration of the loop sets up the post with all of its global variables so post-specific data can be displayed to the end user.

WordPress Global Variables

Global variables are variables you can define and then use anywhere thereafter in the rest of your code. WordPress has a few built-in global variables that can really help you save a lot of time and resources when writing code.

To show a full list of every global variable available to you, run the following code:

<?php
echo '<pre>';
print_r( $GLOBALS );
echo '</pre>';
?>

To access a global variable in any custom code you are writing, use code like this:

<?php
global $global_variable_name;
?>

Some global variables are only made available to you depending on where you are in WordPress. Here is a short list of some of the more popular global variables:

$post

An object that contains all post data from the wp_posts table for the current post that you are on within the WordPress loop.

$authordata

An object with all author data of the current post that you are on within the WordPress loop.

<?php
// set up the database for the SchoolPress app
function sp_setupDB() {
	global $wpdb;

	// shortcuts for SchoolPress DB tables
	$wpdb->schoolpress_assignment_submissions = $wpdb->prefix .
		'schoolpress_assignment_submissions';

	$db_version = get_option( 'sp_db_version', 0 );

	// create tables on new installs
	if ( empty( $db_version ) ) {
		global $wpdb;

		$sqlQuery = "
		CREATE TABLE '" . $wpdb->schoolpress_assignment_submissions . "' (
		  `assignment_id` bigint(11) unsigned NOT NULL,
		  `submission_id` bigint(11) unsigned NOT NULL,
		UNIQUE KEY `assignment_submission` (`assignment_id`,`submission_id`),
		UNIQUE KEY `submission_assignment` (`submission_id`,`assignment_id`)
		)
		";

		require_once ABSPATH . 'wp-admin/includes/upgrade.php';
		dbDelta( $sqlQuery );

		$db_version = '1.0';
		update_option( 'sp_db_version', '1.0' );
	}
}
add_action( 'init', 'sp_dbSetup', 0 );
?>

global $wpdb;
$user_query = $_REQUEST['uq'];

$sqlQuery = "SELECT user_login FROM $wpdb->users WHERE
user_login LIKE '%" . esc_sql($user_query) . "%' OR
user_email LIKE '%" . esc_sql($user_query) . "%' OR
display_name LIKE '%" . esc_sql($user_query) . "%'
";
$user_logins = $wpdb->get_col($sqlQuery);

if(!empty($user_logins))
{
	echo "<ul>";
foreach($user_logins as $user_login)
	{
		echo "<li>$user_login</li>";
}
echo "</ul>";
}

$sqlQuery = $wpdb->prepare("SELECT user_login FROM $wpdb->users WHERE
user_login LIKE %%%s%% OR
user_email LIKE %%%s%% OR
display_name LIKE %%%s%%", $user_query, $user_query, $user_query);
$user_logins = $wpdb->get_col($sqlQuery);

<?php
global $wpdb;
$sqlQuery = "SELECT * FROM $wpdb->posts
	WHERE post_type = 'assignment'
	AND post_status = 'publish' LIMIT 10";
$assignments = $wpdb->get_results( $sqlQuery );

// rows are stored in an array, use foreach to loop through them
foreach ( $assignments as $assignment ) {
// each item is an object with property names equal to the SQL column names?>
<h3><?php echo $assignment->post_title;?></h3>
<?php echo apply_filters( "the_content", $assignment->post_content );?>
<?php
}
?>

<?php
global $wpdb;
$sqlQuery = "SELECT ID FROM $wpdb->posts
	WHERE post_type = 'assignment'
	AND post_status = 'publish'
	LIMIT 10";
// getting IDs
$assignment_ids = $wpdb->get_col( $sqlQuery );

// result is an array, loop through them
foreach ( $assignment_ids as $assignment_id ) {
	// we have the id, we can use get_post to get more data
	$assignment = get_post( $assignment_id );
	?>
	<h3><?php echo $assignment->post_title;?></h3>
	<?php echo apply_filters( "the_content", $assignment->post_content );?>
	<?php
}
?>

<?php
// processing new submissions for assignments
global $wpdb, $current_user;

// create submission
$assignment_id = intval( $_REQUEST['assignment_id'] );
$submission_id = wp_insert_post(
	array(
		'post_type'    => 'submission',
		'post_author'  => $current_user->ID,
		'post_title'   => sanitize_title( $_REQUEST['title'] ),
		'post_content' => sanitize_text_field( $_POST['submission'] )
	)
);

// connect the submission to the assignment
$wpdb->insert(
  $wpdb->schoolpress_assignment_submissions,
  array( "assignment_id"=>$assignment_id, "submission_id"=>$submission_id ),
  array( '%d', '%d' )
);

/*
	This insert call will generate a SQL query like:
	INSERT INTO
	'wp_schoolpress_assignment_submissions'

	('assignment_id','submission_id' VALUES (101,10)
*/
?>

<?php
global $wpdb;
// just update the status
$wpdb->update(
	'ecommerce_orders',   //table name
	array( 'status' => 'paid' ),  //data fields
	array( 'id' => $order_id )  //where fields
);

// update more data about the order
$wpdb->update(
	'ecommerce_orders',   //table name
	array( 'status' => 'pending',  //data fields
		'subtotal' => '100.00',
		'tax' => '6.00',
		'total' => '106.00'
	),
	array( 'id' => $order_id )  //where fields
);
?>

Admin Columns

Admin Columns is a very useful plugin and easily one of our favorites for managing what columns are displayed on the WordPress posts, users, comments, media, and any registered custom post type admin listing pages. This plugin also supports adding custom fields, featured images, and custom taxonomies to your admin columns. This plugin’s super-useful features also include the ability to add sortable columns, editable fields, and exportable CSV files with the columns you have designated. The pro version of this plugin also integrates with Advanced Custom Fields, WooCommerce, and Yoast SEO, allowing you to add any meta fields from those plugins to your admin columns. One of our favorite use cases for this plugin is being able to bulk-edit SEO values for all of my posts on the listing page instead of on each individual post; talk about a time saver!

Advanced Custom Fields

Advanced Custom Fields (ACF) allows administrators to easily set up available custom fields for any post type. It has a very slick admin UI for establishing the fields and the types of fields that are available for a given post type, and backend users can interact with established fields while adding or updating a post. This plugin is also geared towards developers, with lots of custom hooks and filters built in, as well as custom functions you can easily use to display data on the front end. ACF also has a bunch of pro add-on plugins, including:

Repeater field

Allows you to create a set of subfields which can be repeated over and over again, as a way of adding a list of values.

Gallery field

Provides a nice UI for managing multiple images.

Options page

Provides functions for adding extra admin pages to update ACF fields.

Flexible content field

Creates custom layouts with a content-layout UI.

BadgeOS

The BadgeOS plugin can transform any website into a platform for rewarding members, achievements based on their activities. The site administrator can use it to create different achievement types and award the members shareable badges once they complete all the stated requirements for that level. Badges are Mozilla OBI compatible and shareable via Credly.com.

Another very cool gamification plugin for WordPress is GamiPress, which is actually a fork of BadgeOS. In our opinion it’s better maintained and has more features.

Posts 2 Posts

Posts 2 Posts (P2P) is another powerful plugin for building web apps. You can use it to create many-to-many relationships between posts, pages, and CPTs as well as many-to-many relationships between posts and users.

For an example, you could use P2P to make connections between CPTs for schools, teachers, and subjects. A school could have multiple teachers, and each teacher could be tied to one or more subjects.

P2P provides intuitive settings, feature-rich widgets, and an easy-to-use meta box attached to any post add/edit page for making new connections.

Most of the time, custom plugin developers should avoid creating additional database tables unless it absolutely makes sense. If we wanted to connect posts to other posts, we could store an array of post IDs in a custom field of another post, but this can become inefficient in a large-scale application. P2P creates its own database tables, wp_p2p and wp_p2pmeta, for storing the relationships between posts more efficiently; see Tables 3-1 and 3-2, respectively.

For more information on this plugin, make sure to check out the wiki on GitHub.

Members

The Members plugin extends the control that you have over user roles and capabilities in your site. It enables you to edit as well as create and delete user roles and capabilities. This plugin also allows you to set permissions for different user roles to determine which roles are able to add, edit, and/or delete various pieces of content. While it’s possible to apply the information in THIS BLOG to use custom code to change roles and permissions, using a plugin like Members can speed this up for some projects and is absolutely necessary if you need nonprogrammers to adjust these rules at a later time.

The User Role Editor plugin is also popular for managing roles and permissions through a GUI.

W3 Total Cache

Caching your content is a great idea for optimizing the performance of your website. You can save a lot of processing time by displaying cached pages to the end user instead of querying the database every time someone requests data. W3 Total Cache has a lot of built-in features for managing what content gets cached and when the cache should be cleared. More information on using W3 Total Cache can be found in This Post.

Yoast SEO

Yoast SEO is a great plugin to use if you are concerned about search engine optimization (SEO). Once installed, this plugin automatically optimizes your site for search engines. It also adds a preview of the snippet shown in search engine results with fields to override the title and description there. Another useful feature of the Yoast SEO plugin is the “Readability Analysis” report, with suggestions for making your writing easier to understand.

A paid version of Yoast SEO is also available, with advanced features and premium support.

Another popular plugin to address SEO is All in One SEO Pack.

Gravity Forms

An absolute must, the Gravity Forms plugin enables you to easily create custom contact forms for your site. It is an extremely simple process to create a form using the visual form editor, which allows you to drag and drop the fields into the form and reposition them as needed. Standard fields are included as well as the option to create custom fields. The forms are very flexible and can be set up as multiple-page forms with progress bars. Conditional fields allow you to show or hide fields based on selections in previous fields. Another great feature of this plugin is the ability for the forms, once completed, to be forwarded anywhere as chosen by the site admin in the form settings. All in all, this plugin is useful and flexible for anyone needing to create a form on their site, and easy to use for someone without coding knowledge.

BackupBuddy

The BackupBuddy plugin provides you with the opportunity to back up your entire WordPress install for safekeeping, restoring, or moving your site. Backups can be scheduled on a recurring basis, and the file can then be downloaded to your computer, emailed to you, or sent off to the storage location of your choice, such as Dropbox or an FTP server. This plugin also features a restore option that will easily restore your themes, widgets, and plugins. The plugin also allows you to easily move your site to a new server or domain directly from the WordPress dashboard, which comes in handy if you work on a Dev server and then move the sites over to a Production environment upon launch.

WP All Import

The WP All Import plugin comes in handy if you are looking to import data into WordPres from another source that is in either an XML or CSV file, which are two formats not routinely accepted by WordPress. There is also a pro or premium version of the plugin available for purchase that extends the functionality to allow you to import data into CPTs as well as custom fields. The pro version also enables you to import images from a URL and save them in the media library. Also helpful is the ability to set up recurring imports to periodically check a file for changes or updates and then modify the corresponding post as needed.

BuddyPress

BuddyPress is social networking in a box. You can start up a social network with most of the same features as Facebook in a matter of minutes.

You can download BuddyPress from the plugin repository as you would other plugins, or from the BuddyPress site. This plugin has come a long way since version 1.0 was released in April 2009. First built by Andy Peatling, it originally only worked on WordPress MU (Multi User). Automattic, seeing the potential of a plugin that turns WordPress into a social networking application, started funding the project.

Since version 1.7, BuddyPress has been theme agnostic, meaning that if coded properly, it will work with any theme—well, most themes. Prior to version 1.7 (see Figure 3-2), to properly use the plugin, you had to use a BuddyPress theme. This worked well for people wanting to build a social network from scratch because they could use the included default theme, purchase a nice premium BuddyPress child theme, or plan to build their own BuddyPress child theme. However, it was limiting for those who already had a WordPress website because they couldn’t just turn on BuddyPress and have it work with their existing theme. In most cases, people with existing sites that wanted to turn on BuddyPress needed to do customization, which is fine for those who know CSS, PHP, and how WordPress works. But noncoders would need to hire someone to turn their existing theme (which they may have paid for) into a BuddyPress child or compatible theme. But with newer versions of BuddyPress, it just works!

People with existing websites can now use BuddyPress and its features and have them work in their existing theme. It is also very easy to override any existing style to tailor the BuddyPress features more to your website. Special thanks to the more recent core contributors, John Jacoby, Boone Gorges, Paul Gibbs, and todo: (real name Ray Ho) for making BuddyPress what it is today, a theme-independent plugin that turns WordPress into a social network.

Figure 3-2. Welcome to BuddyPress

Components

After activating BuddyPress, head over to the Components panel (see Figure 3-3) in Settings → BuddyPress, or /wp-admin/options-general.php?page=bp-components, to set up components you’d like to use.

Figure 3-3. BuddyPress components

The following components are available:

Extended Profiles

Like any typical social network, BuddyPress has member profiles. A member has complete control of their profile. Out of the box, all members are listed in a members directory; when you click on a member’s name, you’re taken to their profile page.

Account Settings

Members can update their email address, change their password, and even manage the email notifications they receive when other members interact with them.

Friend Connections

Members can add one another as friends. Members ask other membere to be friends by sending and receiving friend requests. Think Facebook friends.

Private Messaging

Members send private messages to one another and view their messages in one place, like an inbox for your social network. Members can reply, mark as read, delete, and perform other actions with messages as with any large social network.

Activity Streams

Members can post activity updates to their profiles and groups, leave comments on other members’ or groups’ activity, and favorite activity posts. Sounds like Facebook, right? BuddyPress has an @mention feature similar to when someone mentions you on Twitter. @mentions automatically link to the mentioned member’s profile page, and if that member has their notifications turned off, they receive an email about it. Activity also comes standard with RSS feeds.

User Groups

A powerful component of BuddyPress, groups can be created organically (or not) by network members. Each group appears on a Groups listing page, and clicking a group’s avatar brings you to its page. The group profile is set up like the member profile page, but with group-specific subpages such as group activity, members, admin settings, and invite friends. Groups can be public, private, or hidden, and members can be promoted to group administrators or group moderators.

Site Tracking

New posts and comments on your site create BuddyPress activity posts. If you are running BuddyPress on a WordPress multisite network, posts and comments created on any site in your network will also create BuddyPress activity posts.

All of these core BuddyPress components can be extended with BuddyPress plugins. It can be a little confusing if you are new to all of this, but you can install additional plugins specific to BuddyPress or build your own. There are approximately 485 WordPress plugins that extend or integrate with BuddyPress in one way or another.

Pages

Once you have decided which core components you want to use, go to the Pages tab at Settings → BuddyPress → Pages, as shown in Figure 3-4. BuddyPress maps the components it is using to new or existing pages. By default, BuddyPress tries to make a new page for each component. If you wanted to call members “Students” instead of “Members,” you could create a regular WordPress page called “Students” and map the members component to this new page. The same goes for other BuddyPress components. You’ll need to create two pages for member registration: Register and Activate. You will need to map both of these to pages if you wish to have open registration on your social network.

Figure 3-4. BuddyPress pages

Note

To allow open registration, you also must make sure that anyone can register; select the “Anyone can register” checkbox under Settings → General.

Profile fields

Located at Users → Profile Fields, this BuddyPress feature allows you to create any number of profile field groups and profile fields for your members. You can collect data such as location, date of birth, likes, dislikes, favorite color, and/or whatever you want. This feature is very flexible in allowing you to organize your profile fields into different profile groups, all of which will be made available on any member’s frontend profile page.

When adding any new profile field, you are provided with a slick UI for deciding whether to make your new field required, what type of form element it should be, what the default visibility is, and whether you want your members to be able to decide if they can change the visibility for the field. This form is shown in Figure 3-5.

Note

By default, all of the profile fields in the “Base” profile group will show up on the registration page.

Figure 3-5. BuddyPress profile fields