WordPress Theme Creation 5: Functionality Plugin Intro

Now we are getting into the really interesting stuff! This is Part 5 in an ongoing free tutorial series about WordPress theming. If you’re just joining me for the first time, I suggest starting at the beginning of the series

here.

What we’re doing this time:

  1. Creating a functionality/helper plugin
  2. Requiring this plugin using TGM
  3. Start adding slider functionality to our plugin
  4. Creating our first shortcode

What is a functionality plugin and why do we need one?

We are creating a creative agency/portfolio theme, right? We will need, amongst other things, a custom post type for our portfolio. Imagine a user has set up our theme with a nice, large portfolio. Good stuff! But, what if they need to change themes, some day, a long, long time from now? Their entire portfolio will be lost if we tie it to our theme. But, if it’s in a separate plugin, it might not be styled appropriately, but it wouldn’t be lost. Besides the custom portfolio post types, we will also be creating a bunch of specific widgets. All this needs to be in a special plugin.

The concept to keep in mind here is: plugin territory. A theme is supposed to determine only the style and layout of your site. Anything that adds additional functionality and won’t still be there once you change themes, is within plugin territory. What we are really creating is not a pure theme. Ours is more of a website solution for creative professionals. But, keeping the style and functionality separate is essential.

Getting started on our helper plugin

We are going to create a plugin and require it in our theme using TGM Plugin Activation, which I’ll talk about in detail later.

Our plugin needs to be completely separate from our theme. It is best practice to ensure that our theme will be completely functional, even if our users choose not to install our functionality plugin. We are going to create a Github repo for it. We need to ensure that TGM successfully requires it from its repo. This is a good structure for our plugin:

->mooi-helper.php // the main configuration file
->inc
	// all our widgets and custom post types will go in the root of this folder
	-->assets
		---> css
			// all stylesheets will go in here
		---> js
			// all scripts will go in here
		---> img
			// all images will go here
->fonts
	// all fonts e.g font-awesome will go here

Create a Mooi Helper(or whatever you’d like to call yours) folder. Inside, create a mooi-helper.php file and add this code:

<?php
/*
Plugin Name: Mooi Helper Plugin
Plugin URI: http://lanigouws.co.za/mooi
Description: Custom functionality plugin which extends the Mooi theme
Author: Lani Gouws
Version: 1.0
Author URI: http://lanigouws.co.za
*/

This is just the start. This plugin obviously doesn’t do anything, but it’s the bare minimum that is required for it to qualify as a plugin that will show up in our list of plugins once installed.

We also need to create activation and deactivation functions inside mooi-helper.php. We will leave them empty for now, but we can write code inside these functions which will apply to specific things that has to happen upon activation/deactivation.

// activation/deactivation
function mooihelp_activation() {
}
register_activation_hook(__FILE__, 'mooihelp_activation');

function mooihelp_deactivation() {
}
register_deactivation_hook(__FILE__, 'mooihelp_deactivation');

You will see that I use the prefix mooihelp for my plugin. Anything you create in the global namespace has the potential to conflict with a theme, another plugin (including one you wrote), and WordPress core itself. Thus, prefix everything with a unique-enough character set.

Note: You need to be pretty comfortable with Git and Github for the next part. Teaching you version control is beyond the scope of this series. If you have never used Git or created a Github repo, I suggest this Udacity tutorial. Github also has a curated set of recommended links called Good Resources for Learning Git and GitHub. It is really quite easy once you get the hang of it.

So, before we carry on: I am going to assume that you’ve commited your plugin to Git and also that you’ve created a Github repo for it. Next, I will show you how we will ensure that new users who install our theme, know about our helper plugin and have an easy way to install it.

Requiring this plugin using TGM

The TGM Plugin Activation plugin is the best way to require and recommend plugins for WordPress themes. It uses classes that are utilized within WordPress, to automatically install, update and activate multiple plugins that are either bundled with a theme, downloaded from the WordPress Plugin Repository or downloaded elsewhere on the internet (like our Github repo).

Go to its download page and enter your specific details. See the image below:

wordpress plugin

Then click the Generate button.

Unzip the downloaded folder and copy the class-tgm-plugin-activation.php into your theme’s inc folder. Then open your functions.php and add this code to the bottom:

/**
 * Load TGM Activation file.
 */
require_once get_template_directory() . '/inc/class-tgm-plugin-activation.php';

The next thing we need to do is to create a function to configure the plugin and and hook it to tgmpa_register via the add_action() function. If you look at the plugin folder, you will see an example.php file. This pretty awesome file provides you with complete examples of how to write this required function for every possible kind of plugin you might require. All we need to do is copy the specific configuration for our use case to our functions.php. So, add the function like this(be sure to change the details to apply to YOUR plugin:

/**
 * Register the required plugins for this theme.
 *
 * This function is hooked into `tgmpa_register`, which is fired on the WP `init` action on priority 10.
 */
add_action( 'tgmpa_register', 'mooi_register_required_plugins' );

function mooi_register_required_plugins() {

	$plugins = array(

		// Include the Mooi Helper plugin from its Github repo.
		array(
			'name'      => 'Mooi Helper',
			'slug'      => 'mooi-helper',
			'source'    => 'https://github.com/Lanigo/mooi-helper/archive/master.zip',
		),
	);

	$config = array(
		'id'           => 'mooi',                 // Unique ID for hashing notices for multiple instances of TGMPA.
		'default_path' => '',                      // Default absolute path to bundled plugins.
		'menu'         => 'tgmpa-install-plugins', // Menu slug.
		'parent_slug'  => 'themes.php',            // Parent menu slug.
		'capability'   => 'edit_theme_options',    // Capability needed to view plugin install page, should be a capability associated with the parent menu used.
		'has_notices'  => true,                    // Show admin notices or not.
		'dismissable'  => true,                    // If false, a user cannot dismiss the nag message.
		'dismiss_msg'  => '',                      // If 'dismissable' is false, this message will be output at top of nag.
		'is_automatic' => false,                   // Automatically activate plugins after installation or not.
		'message'      => '',                      // Message to output right before the plugins table.
	
	);

	tgmpa( $plugins, $config );
}

Now, if you did everything correctly, you should see this familiar message when you go to your Dashboard:

wordpress plugin

Go ahead and install your plugin.

Start adding slider functionality to our plugin

You can find the plugin in its Github repo. If you download the .zip, you will also find the images you need for the next part of the tutorial.

One element you see in most modern websites, that is firmly within plugin territory, is sliders. We will be adding a slider to our theme, through a custom post type in our helper plugin.

I want to keep our plugin well organized. So, for every post type or widget we add I want it to have its own php file inside our inc folder. Then we’ll require them in our main plugin file. So, firstly add this code to your mooi-helper.php:

/**
 * Include the file with the slider code.
 */
require_once plugin_dir_path(__FILE__) . 'inc/slider.php';
?>

The next thing we need to do is to download the actual slider we are going to use. This part of the tutorial is loosely based on this tutorial from 1stwebdesigner.com. It is the only really complete tutorial I have found on the subject of creating a slider plugin. The tutorial was also written especially for designers, so everything is explained very simply. So, the slider plugin we are going to use is SlideJS, which can be downloaded from the provided link. My aim is to give you the tools to create your own plugin with the slider of your choice.

Once downloaded, you can copy the main JavaScript file called jquery.slides.min.js into your js folder. We also need to create a file to initialize our slider. Create a file called slides.init.js, save it in your js folder and put the code below inside it:

jQuery(function() {
      jQuery('#slides').slidesjs({
        height: 528,
        navigation: false
    });
});

We are going to include Font Awesome, just like we did in our theme. So, copy the fonts folder into the root of your plugin. You also need to copy the font-awesome.min.css into your plugin’s css folder. Lastly, we are going to add our own styles. Create a file called slides.css and put these styles inside:

/*!
 * Unique slider styles
 */
.slider-container {
  margin: 0 auto;
}

.slidesjs-pagination-item {
  display: inline;
  float: right;
}

.slidesjs-pagination {
    margin: 6px 0 0;
    float: right;
    list-style: none;
}

.slidesjs-pagination li {
    float: left;
    margin: 0 1px;
}

.slidesjs-pagination li a {
    display: block;
    width: 13px;
    height: 0;
    padding-top: 13px;
    background-image: url("pagination.png");
    background-position: 0 0;
    float: left;
    overflow: hidden;
}

.slidesjs-pagination li a.active,
.slidesjs-pagination li a:hover.active {
    background-position: 0 -13px
}

.slidesjs-pagination li a:hover {
    background-position: 0 -26px
}

ul {
  list-style: none !important;
}

Now that we have all the stylesheets and scripts we need, we can enqueue them in mooi-helper.php

/*
* Enqueue the slider scripts
*/
function mooihelp_scripts() {

	wp_enqueue_style('mooihelp_slidesjs_style', plugins_url( 'inc/assets/css/slides.css', __FILE__), '' );

	wp_enqueue_style('mooihelp_font_awesome', plugins_url( 'inc/assets/css/font-awesome.min.css', __FILE__), '' );
	
	wp_enqueue_script( 'mooihelp_slidesjs_core', plugins_url( 'inc/assets/js/jquery.slides.min.js', __FILE__ ), array( "jquery" ), '', true );
	 	 
	wp_enqueue_script( 'mooihelp_slidesjs_init', plugins_url( 'inc/assets/js/slides.init.js', __FILE__ ), array( "jquery" ), '', true );
	 
}
add_action('wp_enqueue_scripts', 'mooihelp_scripts');

Our next step is to code the function that will create the html for the sliders. First, we will create a static slider. Once we have everything down, we’ll add the code that allows users to create their own unlimited sliders.

Creating our first shortcode

WordPress offers a predefined shortcode function to create shortcodes in WordPress plugins. When using the shortcode function, you have to define a handler function that parses the shortcode and returns an output. Then, you need to register a shortcode using the add_shortcode() function. Below is an explanation of the required shortcode code.

add_shortcode( $shortcode_name, $handler_function);

$shortcode_name – (required, string) It is a string to be searched in the post/page.
$handler_function – (required, callable) It is a hook to run when shortcode is found.

Once this code is created, you can reference the shortcode [shortcode_name/] anywhere.

So, now that you have some background about shortcode creation, let’s create one for our slider. Put this code in the empty slider.php file you created earlier:

<?php
/*
*   The function to display sliders
*/

// Shortcode for sliders
add_shortcode('mooihelp_slider', 'mooihelp_display_slider');

Also in slider.php, add the ‘handler function’ which will create the slider with the temporary HTML (also remember to put the referenced images in the img folder

// The handler function to display the slider and images
function mooihelp_display_slider() {
$plugins_url = plugins_url();
echo '<div class="slide-container">
    <div id="slides"> 
        <img src="' . plugins_url( 'assets/img/example-slide-1.jpg' , __FILE__ ) . '" /> 
        <img src="' . plugins_url( 'assets/img/example-slide-2.jpg' , __FILE__ ) . '" /> 
        <img src="' . plugins_url( 'assets/img/example-slide-3.jpg' , __FILE__ ) . '" />
        <img src="' . plugins_url( 'assets/img/example-slide-4.jpg' , __FILE__ ) . '" /> 
            <a href="#" class="slidesjs-previous slidesjs-navigation">
                <i class="fa fa-chevron-left icon-large"></i>
            </a>
            <a href="#" class="slidesjs-next slidesjs-navigation">
                <i class="fa fa-chevron-right icon-large"></i>
            </a>
   </div> 
</div>';
}

Good stuff! Now try it! Use our shortcode [mooihelp_slider/] anywhere in a post or page to try it out. To use the shortcode in any template file, you can use this code: <?php echo do_shortcode( '[mooihelp_slider/]' ) ?>

Of course, we are just starting. Our users will currently only have the ability to create a static slider with only the images we referenced in our static HTML. But, we are well on our way. Next time, we will complete our slider. We will give users the ability to dynamically add images and create unlimited sliders, using unlimited shortcodes.

Until then,

Happy coding!

One thought on “WordPress Theme Creation 5: Functionality Plugin Intro

Leave a Reply

Your email address will not be published. Required fields are marked *