Why theme documentation matters

Creating WordPress themes can be fun. Sharing them with everybody is even better. What happens when those users then ask you how to do something? Often times what is the simplest task to you may seem like a trip to Mordor for others. You don’t always know the person’s knowledge base when you share your theme. They could be a developer that began using BASIC when it was first introduced, or a person who has just picked up a book on how to build a website using WordPress.

What’s cool is we can meet both those worlds in the middle. One way is by using code comments. Code comments can make it easier for not only yourself but others to know what exactly the code is doing. A good example of this is the comment block below, taken from the wp_get_theme function:

/**
 * Gets a WP_Theme object for a theme.
 *
 * @since 3.4.0
 *
 * @global array $wp_theme_directories
 *
 * @param string $stylesheet Directory name for the theme. Optional. Defaults to current theme.
 * @param string $theme_root Absolute path of the theme root to look in. Optional. If not specified, get_raw_theme_root()
 * 	                         is used to calculate the theme root for the $stylesheet provided (or current theme).
 * @return WP_Theme Theme object. Be sure to check the object's exists() method if you need to confirm the theme's existence.
 */

Yes, it can look like a lot of information but not all your code has to be as robust as that. You can use simple documentation and still do just the same. While that does go for some developers, we cannot forget those that just want to use the theme and are possibly afraid of code, or don’t know how to code. Great! This is where other forms of documentation come in handy.

Types

There are other forms of documentation that you can use to your advantage. A few I like are:

  • Videos
  • Images
  • Readme file

Please note, images and videos may not always be view-able by all so you may have to take that into consideration on your path to documentation bliss. Now, let us explore those a little more.

Videos

I love me a good video. A video tutorial, that is. Now, your theme does not have to have a step by step video on how to setup every single option, or possibility your theme offers but you do want to have some of the basic, and perhaps most common things. A few examples are installing the theme, accessing your theme options, showing how to setup possible social links, or even using page templates. You don’t have to have audio but it does help. There are several programs out there that allow you to capture video and create video screen casts.

Images

Yes! Images can make a huge difference for many. Even better when they move. I am talking about gif images. They can be a great way to showcase a few steps without having to create a two minute video to show how to access extra options. If you have an image editing program it can be used to highlight what you want in order to emphasize parts of the image.

Readme File

The basic and standard file you need to include. Okay, that’s just me saying it but I’m sure there are more people who would agree with that statement. This is the part that really irks me because you can include some basic steps that can go a long way. A great example is setting up social link profiles. There are several ways of creating those and not all themes follow a standard. It is nice to know where to look and how to use it.

== Setting up social links ==
1. From Dashboard go to Appearance
2. Click Customize
3. Go down to Social section
4. Type username or ID ( depending on network )

Looks fairly simple, right? It can be for some but there may be others that may still get confused. Okay, we covered a simple setup but what happens when a user gets what they feel is an unexpected result?

What do I mean by this?

Let’s say the theme has a menu location at the bottom and you only want it to display one level of menu items. They may open a support request, thread, ticket, whatchumacallit, or what ever system of support you are using and ask why it isn’t showing all the menu items. This is where your theme’s documentation can come in super handy and essential. If it is a design choice then it should be stated in the documentation. A good way would be something like:

=== Limitations ==
* Featured images should be minimum 600 pixels wide and 400 pixels tall for best results
* The `footer-nav` menu location, by design, only displays one level of menu items
* The `ad-loc-1` widget area is only used in the page template `fullwidth-ads`
* If pages do not have a featured image set, the chosen header image will be used

Yes, even what sounds -or seems- strange is super helpful to the user of your theme. Knowing what the best size for an image is useful, just like knowing the right size of tire for your car or bicycle.

So please, please make sure you are documenting for not only yourself but for your users as well.

All about my Child – Theme that is

Frequenting the WordPress support forum always makes wonder a lot of things. The biggest one, I hate to admit, is do people read. I know it does come off a little mean, rude but the truth is a lot of the threads that are in the forums could easily be avoided. The number one being how to modify a specific theme.

The forums are filled with a few of these but the biggest mistakes is that people don’t really read. I want to say part of that reason is the welcome page to the forums. Don’t get me wrong I can find my way quite easily since first starting over a year ago but for a first timer you will want to look elsewhere.

The thing that people want to be able to do is modify a theme or alter it to make it their own. The best way to do this is by creating a child theme. The codex has a good quick and simple tutorial and then gets a little more detailed about how child themes function.

I’ll break things down into steps. Why? Because that’s how most of us read and follow directions, right?

  1. Create empty folder
  2. Create style.css
  3. Active

Create an empty folder

One of the first things to do is create a folder. It really doesn’t matter what you name the folder. 

Create a new folder
Create a new folder

I chose twentysumchild for demonstration purposes but it really could be anything you want. In that folder we will then create a new file. It will be the main file for our child theme. Can you guess the name? Yep,

style.css

will be the newly created file.

Create style.css

Pick any text editor and you will add the needed format so WordPress knows what to do and how to interact with our newly created theme. In our randomly named folder we will now have a single file called: style.css

In this file we will add the CSS header information so that WordPress will show it on our Themes selection page.

Sample information for style.css
Sample information for style.css

As you can see I chose to name my child theme ‘My Randmoizer’ but really it can be anything you want it to be. The key to making the child theme is actually the keyword “Template.” It sounds a little odd but it is true. If you for some reason get a message that there is a template file missing it may be due to that missing line of code.

Now all that is left is to activate the theme.

Activate

Child theme activated
Child theme activated

I didn’t use a screenshot only because I didn’t have much time and I got a little lazy towards the end. A good size for one is 600 pixels by 450 pixels.

As you can see I chose to base my child theme on Twenty-Thirteen but you can create a child theme from just about any theme. Just don’t forget that the key word is: Template

So go, explore, tweak and hack away to your heart’s content. Make as many changes as you want knowing that you will not lose any changes when that theme gets updated.

Creating a sticky post slider

Brief background

Creating a slider is simple. For some. In WordPress there are a lot of ways to creating a post slider, image slider, category slider and just about any type of slider you could possibly imagine. The one I wanted to share is creating one with sticky posts. You know the ones that you have to pick from the slightly hidden options.

Make post sticky

Yeah. That little guy. The way WordPress handles sticky post is by putting them on the front page and keeping them on top regardless of when it was posted. A good example is the quick image I created to help illustrate.

The requirements

WordPress has plenty functions and plenty of ways of getting the required posts. One way of getting posts is using get_posts() but that isn’t the method I’ll be using. I’ll be using the WP_Query and alter it just a little bit. No, not with query_posts because that will just cause the world to implode. Okay, not really but there are several other reasons not to use that function.

The steps

In order to have a good functional featured post slider we first need to layout the steps needed. What I did initially was make a quick list of the steps.

  1. Get the posts
  2. Check if there are any ‘sticky’ posts
  3. If there are then run our code
  4. Ignore sticky posts in regular feed
  5. Drink up

The code

Now that we have our logic we can get started.

The first thing we have to do is get all the posts that are set to be sticky. We create and array to hold these.

$stickies = get_option( 'sticky_posts' );

We need to count how many posts there are and we’ll store that as a variable so we can use it later on.

$count = count( $stickies );

Now that we have an array and the total we can start a new query for only those posts. The way we do this is by creating a new WP_Query and passing some arguments. So we’ll create these arguments and name our newly created object of posts $featured. It can be whatever you want it to be. If you are submitting to the WordPress repo then prefix it with your theme or equivalent.

$args = array(
	'post__in'       => $stickies,
	'posts_per_page' => 3,
	'post_type'      => 'post',
	'nopaging'       => true
	);
$featured = new WP_Query( $args );

Now that we have our new object filled with posts we can run our code with the newly created query. But wait! When WordPress is first installed there are no sticky posts so then how do we check for that? Simple. Remember that we stored the value into a variable called $count? We’ll use that. We’ll use an if statement to run our code. If there are no posts then we’ll begin the newly created WordPress loop.

if ( $count > 0 ) {
  // run WordPress loop using $featured
}

Sounds simple now that we have it all together, right? Now we can create the loop and fill it with all the goodies and information we want using template tags. Don’t forget to use wp_reset_postdata() to reset our post data. There is one last thing we must do to get it all working right and that is hooking to pre_get_posts.

What?!

One more thing?

Yes, one last thing. I know a bit of a curveball but this is what will prevent the doubling of sticky posts. What we have to do is add just a few lines of code to our functions file of our theme.

add_action( 'pre_get_posts', 'my_awesome_theme_pre_posts' );
function my_awesome_theme_pre_posts( $query ){
    if ( is_home() ){
        $query->set( 'post__not_in', get_option( 'sticky_posts' ) );
    }

    return $query;
}

Now that we have that done we have our final code snippet:

// Create array of all the sticky_posts
$stickies = get_option( 'sticky_posts' );

// Count how many there are, if any
$count = count( $stickies );

// Create a set of arguments to pass
$args = array(
	'post__in'       => $stickies,
	'posts_per_page' => 3,
	'post_type'      => 'post',
	'nopaging'       => true
	);

$featured = new WP_Query( $args );

// If there is one or more sticky post we create our new slider
if ( $count > 0 ) : ?>
<section class="featured" id="featured-slider">
    <?php while( $featured->have_posts() ) : $featured->the_post(); ?>
    <article <?php post_class( 'featured' ); ?> id="post-< ?php the_ID(); ?>">
        <h1 class="featured-title"><?php the_title(); ?></h1>
        <div class="content"><?php the_content(); ?></div>
        <div class="content"><?php wp_link_pages(); ?></div>
        <footer class="meta">Posted: <?php the_time( get_option( 'date_format' ) ); ?></footer>
    </article>
    <?php endwhile; wp_reset_postdata(); ?>
</section><!-- end of our featured article slider -->
<?php endif; // end the featured posts ?>

Enjoy

And done! For the most part since we need to add interaction but I’ll let you pick out what to use since there are plenty of jQuery slider plugins to help with that.