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.

Using a post as a menu item

Truly a neat little find for many people. I know when I saw this for the first I was beyond astounded.

It does seem a little odd to use one but there are some random cases when it can be useful. Rather than having to use a page you can use a post. Granted it will show up with all the other posts but it is a cool thing to know.

There are a few steps required:

  1. Create the post.
  2. Create a menu
  3. Create the menu item

The first thing is, of course, to create the post. Could be anything you want about whatever you want. A cat, a dog or even a random turtle you saw the other day.

Next, you want to create a menu. In order to do so you want to go to the Appearance section and select Menus. That will bring up the Menus screen. If you don’t already have a menu created, name it whatever you want and press the create button.

Finally, we create the menu item. This is where it can be a little tricky. Why, you ask? Well, by default WordPress shows three options. You can actually have more. You just have to look in the right place.

screen-options

When you click on the Screen Options tab you get a nice little selection of things that you can now edit. As you can see from the following image you now can choose tags, categories and even posts as menu items.

new-options
Options galore!

From there you will choose what you want. In our case we will check off all the options because we like to live dangerously and love options.

Now we see that have a few more things in our roster of options.

new-menu-options

From there we can now choose posts as menu items. Awesome, right?

Uploading and updating your theme

It’s no secret I love doing theme reviews. When I get a chance. The past couple of weeks though I’ve only been able to do one a week if I’m lucky. I do read the theme-reviewers emails when I open my inbox but of course that just isn’t enough.

Background

If you didn’t already know for the last year I’ve been stating that I am working on a theme to submit. Yes and no. The biggest thing I’ve actually been working on is a personal theme. for this site. I’ve looked at many themes and have even thought about purchasing a theme from an established, and reputable theme foundry. As you can tell I chose to use the Displace theme.

For the time being I like and it does the job. I’ve thought about modifying it but want to create my own. Maybe down the road. We’ll see. I’m getting a little sidetracked so we’ll talk about the issue at hand. Updates and the review process.

Uploading a new theme

themes-directory

The process is actually quite simple. One of the first things you want to do is go to the themes directory. As you can see from the image on the right hand side the welcome screen showcases a few featured themes and on the right hand column there are three sub-sections: Popular, Newest and Recently updated.

You will want to login with your WordPress.org username and password. After you have done that you have, and I mean have to, read more about having your theme hosted in the repository. I cannot emphasize that part enough, either. In particular the guidelines to getting your theme accepted.

That little about page is very crucial and does look a little like:

themes-directory-2
Read! And I mean read this page.

Yeah, it does seem a little daunting but it is fairly simple and straight-forward. Some information about theme-tags, guidelines and why you would want your theme in the repository.

So, you’ve signed in and want to upload your theme. You go to the upload section by clicking the Theme Authors link and you are taken to the upload screen. This is the crucial one you will want to store not only in your bookmarks but in your head as well. This page is what will create a new Trac ticket with your theme so that an actual human being will go over your code and give you feedback and hopefully approve your theme.

A ticket?

You read that right. A ticket. You will receive an email confirmation with that ticket number. If that doesn’t happen you may want to contact the theme-reviewers list and I’m pretty sure at least one person will be able to help you out.

themes-trac-intro

The next stage is the review process. When I started doing reviews it was a little tedious, to say the least, only because so much of the process wasn’t as automated as it is now.

What a reviewer would do is login to the Trac for WordPress themes, go to the report, as demonstrated in the next image, and see if there were any other tickets that have been submitted using the same username/theme and close the tickets. The reviewer would then conduct the review with the most current version of the theme.

trac-ticket-queues

What next?

The next thing you will be getting is feedback. Good, bad and maybe even some ugly. We don’t always like to hear the truth but let’s face it. We don’t always do our best the first time around. I know I don’t.

previously-approvedFrom here on out it will be a human being, an actual living, breathing, eating, human being that will read over your lines of code. That person will read every character and see every image you used to create that WordPress theme. And hopefully, just hopefully it will pass inspection. The key here is communication. Get a dialogue between both you and the reviewer. A great example is a review I did a few weeks ago to the Customizer theme as seen on the image to the left.

Now, I know you’re wondering why such a long list of tickets that developer has. At least those that looked at the image. That was because some of those are updates. If you’re not asking how you update your theme then I’m not sure we can keep talking. In real life. I kid of course.

In order to update not only your theme in the repository, but in the theme trac you will want to visit the upload page once more.

upload-signedAfter you have signed in, naturally, you will head back to the upload page, make sure you bump the version of your theme in your stylesheet and you will be on your way to sharing with the WordPress community.

 Final thoughts

As I said the key is communication. Talk to the person conducting the review and the developer. You would be amazed about what both parties can learn and you also may make a new connection in the end.

Be friendly and filter your foot

HTML5 footer

A brief glimpse of my WordPress.com hosted blog’s footer. I’ve had that thing for nearly six years. Yep, six years. A little hard to believe that I only have about eighty posts but it’s true. Part of that reason being me branching off and trying on a self hosted site. I wish I could tell you all the things I’ve tried over the course of this branching but honestly don’t recall every little thing I’ve done.

I can honestly tell you I have learned a few things here and there from not only reading the WordPress codex  pages but from doing some theme reviews as well.

Be friendly

Yes, be friendly. What I mean by this is that you should think about who will be using your theme or plugin. True that not many people are capable of knowing how to code a site with PHP, HTML but that may not be your target, right? Odds are that you want to share your theme with the community.

That means that another developer will be looking at your code. Shock! Awe! You name the emotion, odds are that person will experience it at one point while looking at your code. The one you don’t want to bestow upon them is anger. Once that one hits their ability to trust you will dwindle.

How do you prevent it? Well, documenting is a great way. Another is by making things a little easier by adding hooks and filters to your theme.

Hooks and filters

Yes, hooks and filters. One simple solution to help everyone out. At least a good portion of people. You can’t really please everyone, unfortunately. One way of adding friendliness to your theme, or plugin, is by adding a simple action so that a child theme can easily hook to it. A quick sample would be just before the page of the theme.

< ?php do_action( 'page_prior' ); ?>
    

See? Simple, right? Then all a child theme, or even a plugin, has to do is hook to it. Now, that is a quick and painless way of making your theme a little easier to work with and a future developer will like it since they won’t have to change any files or create a separate file. But there is more! What’s even crazier to think about is that you can not only create minor changes that way but you can also make huge changes that way.

Suppose for a moment that you create a post structure that you feel would want to be changed down the road or by somebody else. Simple! You guessed it! Action hook. Now it is a little more work but you can do it with a few extra lines of code.

//somewhere in the index file
while ( have_posts() ) : the_post(); 
 do_action( 'theme_content' ); 
endwhile;

// in the functions file
add_action( 'theme_content', 'theme_content_cb' );
function theme_content_cb(){
    // inside the WordPress loop
}

Yeah it does look a little odd. But in the child theme’s function file all you would have to do is remove the action and add it again with your own callback function. So the child theme’s function would look a little like:

remove_action( 'theme_content', 'theme_content_cb' );
add_action( 'theme_content', 'child_theme_content' );
function child_theme_content(){
    // My child theme's content code
}

What is nice about that is you can easily alter an entire block of code without ever having to touch any parent theme files or having to create any duplicate files and modifying to your choosing. It is very convenient when you have to remove credits sometimes. One of the issues I see in the WordPress.org Themes and Templates forums.

Filtering

Filtering the output is key in this. Why? Because it makes things just that much easier for the developer that will be using the theme. Remember to keep your audience in mind when creating a theme, or plugin. A good portion of the time it will be a developer. Adding a filter is as easy as using

apply_filters

and you’re done.

function theme_footer_cb( $theme_footer ){
    $theme_footer =
    ';
    echo apply_filters( 'theme_footer_cb', $theme_footer );
}

With that any themer can filter the output of the theme’s footer by adding a filter in the child theme’s function file like so:

add_filter( 'theme_footer_cb', 'child_theme_footer' );
function child_theme_footer( $footer ){
    $footer = '
Created with LUV
'; return $footer; }

Not so hard, right? Now go out and make a developer happy by creating these simple little hooks and filters.

Understanding arrays

Backstory

For the last month I have read about JavaScript ( ECMAScript ) and how it works. To say the least I am one step closer to not being as bald as I thought I would be. JavaScript is a great language to learn and has so much potential behind it and for it.

What caught me a little off guard was the term object-oriented. For the longest time I hadn’t the slightest idea what that meant. I finally reached that pivotal moment when it hit me. That little moment of: that makes total sense.

What are arrays?

Arrays, simply put, are lists. Yes, it does sound sort of strange but it is true. Arrays are lists. In just about any programming language arrays are used to store not only information but information about that information. Yes, more information within information.

A great way of thinking what arrays are is to think of them as lists; which is kind of what they are. A good example is the little JavaSvript snippet:

var groceries = new Array( 'tomato', 'cucumber', 'squash', 'zucchini' );

Simple right? Now, what if we want to deal with and store more information? For that we introduce associative arrays.

Associative Arrays

Not the suit wearing type but the mathematical type. At least for me it makes sense. Not sure if it will help anybody else but here goes. An associative array is an array within an array.

Inception much?

A really great way to look at this is by not only looking at the code but thinking about lists. Yes, lists. Again. A great example of this is a restaurant’s menu.

$menu = array(
    'pizza' => array( 'cheese', 'pepperoni', 'sausage' ),
    'potato' => array( 'fried', 'baked', 'chopped', 'chip' ),
    'drink' => array(
        'soda' => array( 'diet', 'regular' ),
        'alcohol' => array( 'beer', 'wine' )
        ),
    'salad' => array( 'house', 'caesar' )
    );

Wow! That is quite a bit of code to show my point but I will run through it pretty quickly.

We start with the basic menu items: pizza, potato, drink and salad. Each one of those items then has its own bit of information attached to it. Pizza has the toppings, potato shows how it is cooked, the drink one is a little tricky in that it has two different arrays for soda and alcohol.

Get it? Got it?

And there we have a small glimpse of how I am capable of understanding arrays and associative arrays. Very dumbed down but it is a very clear way of looking at it.