Grunt your way to automation

WordPress theme development can feel repetitive. At times there are things you are always doing over and over again. This is true when you are building a WordPress theme for distribution. Thankfully there are tools that can make your workflow a bit easier.

Tools

In order to make your theme workflow a little easier we will need a few things.

Yes, a few things to set up but when you are building a roller coaster you don’t use just one tool, right? Same applies to building a theme – or even a plugin.

Grunt can make your life easier by taking redundant tasks and automating them. A good example of this is minifying all your files. The big benefit of this of course is a smaller file size but what happens when you have to redo this when you change the main file? You have to re-minify. What if you have more than one file? This can be frustrating because you may have to do this so many times.

This is where Grunt comes in super handy. It helps run repetitive tasks like minifying, copying, and even compressing things for us.

My gripe with widgets

Yes, I don’t like widgets. Okay that is not entirely true because I am using a few but it’s not what I’m referring to. What I’m referring to is when themes include widgets.

Themes that include widgets for contact forms, testimonials, group -or team- members of a company. Dare I say it? Newsletter widget. Cue dramatic music. Yes, I am referring to most of those. The reason I hate them is because you lose it once you switch a theme. It reminds me of the shortcut icons I see being used by a lot as well. It does drive me up a wall.

Up a wall, you say?

Yes. The reason for that is because there are dozens, and dozens of plugins that can do it and possibly do it better. Some things are not meant to change. The shortcut icon ( favicon ) should be one. In my opinion some widgets should be the same way. I make an exception only because I know there is at least one theme that unregisters core widgets and includes their own extended version of that widget. You still lose that functionality ( keyword right there ) once you make a switch to a new theme.

I know you may be asking and even wondering what argument, or arguments, could be made. Well, some people never change their themes. True. The thing to remember too is that even down the road they may just think about changing that theme. It will be a bad experience once they change that theme and lose the widget(s) they had.

There are some that are purely aesthetic and add to the theme’s experience but should that be the end all to turn to for widget design, functionality? I don’t know but it does seem a little strange that I haven’t seen many themes proclaiming support for certain widgets.

Start a trend

Yes, it would be nice. At least to see some theme authors supporting more and more plugins or specialized widgets. I mean after all that is what the description is for or even the theme’s documentation, right?

Making a Portable Object Template for your WordPress theme or plugin

Yes, a bit of a lengthy title but I feel will get the point across and it is after all what I’m wanting to share with you today.

A what now?

A .pot ( or a Portable Object Template ) file is what WordPress uses and many PHP programs use for translation purposes. There are three files used. According to icanlocalize.com the files are:

  • MO – Machine Object. The MO file includes the same contents as PO file. The two files differ in their format. While a PO file is a text file and is easy for humans to read, MO files compiled and are easy for computers to read. Your web server will use the MO file to display the translations.
  • PO – Portable Object. This is the file that you receive back from the translators. It’s a text file that includes the original texts and the translations.
  • POT – Portable Object Template. This is the file that you get when you extract texts from the application. Normally, you send this file to your translators.

The one we will worry about is the last one. The POT file. There are several ways to create this file but the one I’ve found most useful was the one Otto was awesome enough to post for theme reviewers. It is super simple and does need a little tinkering and getting over the fear of the command line.

Yes, the command line. You know that little program that uses only text. No, not a text editor. Would be cool but no. Depending on the platform you are using it will be called a terminal window, command prompt or even powershell. All of these will work for what we will be creating.

Steps and requirements

Sorry, did I not mention there would be some requirements? The basic requirement is the command line and having PHP installed. The next would be getting the needed files from the repository. If you aren’t developing themes using a development version of WordPress leave your address in the comments below, I will find you and I will hit you. Hard. Even a release candidate is worth your investment unless you like to break things and have people yelling at you.

The tools and files you will need are in one of two locations. The first being in the svn developer site. You will need some sort of SVN software in order to get it, of course. The other would be from my github repo I created and modified. Yes, I created it just for this reason.

So the steps are as follows:

  1. Get files
  2. Extract files to correct folder
  3. Open command line
  4. Do some magic – or Voodoo, your choice
  5. Do happy dance!

Getting the correct files

I mentioned and linked two places where to get the needed files. The github link is the one I will go over. Part of that reason is not everybody will be fully familiar with version control or comfortable enough to not break things. Once that is downloaded we can open the zipped folder and move on to the next step!

Extracting the files

This is super simple thing to do. Extract the files to the root of your WordPress folder. It should look something like the image.

WordPress folder
WordPress folder

Open the command line

Now, there are several tools that are available for this. For Windows user there are two that I will often switch between: command prompt and powershell. I like using powershell more. We then will change to the directory where we have our WordPress installation.

For the next step will be going over some code, so be prepared.

Doing the magic

So here is where the real magic will happen. Once we are in the folder of our installation we will once more change directories to the i18n folder where all translation files reside. From there we will run a quick line of code that will create our new POT file.

$ php makepot.php wp-theme /path/to/theme /path/to/languages/theme-slug.pot

The thing to keep in mind is the $ is just a placeholder for the current directory you are in. It may differ from machine to machine. Once we have run that it will create a new file ( theme-slug.pot ) with all translation-ready strings. So try not to forget to translate all text strings!

How it works

I know there are a few people wondering how this actually works. I know I was for bit. I’ll try my best to make it a little more understandable why you need to have certain things in your command line.

The first thing you need to know is what you are doing. When you state php you are to a degree saying, “I want to run PHP code and use this file.” The next three things are what you are going to pass that file.

  1. The first thing we passed is what type of project you are creating the pot file for. In our case it is a wp-theme. There are a few other you can decide from like wp-plugin, wp-admin, wp-core and a few more that I just won’t list.
  2. The second thing we passed is the location of where to look for the translation functions. If you read through the list of what functions it looks for you are in for a treat because that list you can add to Poedit. (I’ve slowly walked away from that but would still recommend for beginners.)
  3. The last thing is the output of the file. Both the location and the name ( be sure to include the extension as well ) are what we will be using.

Now, you can do this with your plugins as well. Just be sure that the folder you are creating the POT file to does exist otherwise you will get errors and it won’t create the file for you.

I stated earlier that it works with a few changes; it’s true. The reason being I know there are some people who don’t like to use a development version of WordPress. Why? I don’t know but I made a few tweaks for it to work the way it works. Okay, I only changed three things but it works for the time being. I say that only because I’ve tested it on/off since the original post. If you encounter any issues please be sure to let me know!

Celebration will begin

There we have a newly created POT file ready to be sent to a translator. So, yes, by all means do your happy dance. Not only did you get over the slight fear of the command line but you possibly learned something new along the way.

Notes

If you don’t specify a path of where your theme/plugin resides it will create an error and will not work!
If you don’t specify a path, just a name for the file it will create the file in the i18n folder.

Organizing all the media

Yeah, media. I love it. Most people live it and some are just indifferent about it. Blah! Is what I say to them. The reason I say it is because I love entertainment. Surprised? Don’t be. I am super easily amused. Like super easy. Like two-year-old easily.

A little history

The last couple of months I was trying to think of a way to organize my media library. No, not my computer. That would require way too much effort on my part and I just don’t have the attention span for it. I mean for my WordPress site. One thing that I felt could be improved. At least the experience.

My current library is the default one. Why? Because I never got a chance to get to it. I’ve wanted to change the layout for some time and use a grid system to display all the items. Do keep in mind I mostly have photos and very little audio and little-to-no video. For the time being. I will change that down the road, of course.

So here is the current look:

Media Library core

Recently I came across an amazing plugin that helped me do what I would like to do. At least for the time being. It’s called media grid. Simple solution that will hopefully make its way to core. As I write this out I’m also testing the development version and tweaking, trying to figure out how to break things and where it may break. It’s fun. You should try it one day. As Ferris Bueller once said:

“It is so choice; if you have the means, I highly recommend picking one up.”

Yes. I do believe in the plugin that much. Enough to write about it. Running through the paces I do have to say I love how it works on a desktop environment. The ability to change from thumbnail to a larger image is nice and being able to batch delete is great. Next phase – I feel – will be being able to preview the other media. Do remember that ever since WordPress 3.6 video and audio support were added and there are several plugins that also add other formats to the mix.

For me, the ones that matter most are video, audio, and of course images. So with the plugin enabled it does look like:

media-grid It is a little edited since the version I’m using wasn’t playing nice with the screen but that gives you an idea of what to expect. Pretty cool, right? So go, download it, try it out and if you’re feeling up to it: review it!

You don’t know text

Okay, maybe you do but what I’m talking about is a different kind of text. I’m talking about text strings in PHP code.

Text strings

What are they? Why do they matter? Well, they matter in themes that you want to make public or share. Oh, and plugins as well, I guess. If you’re into that sort of thing.

Over the last few weeks I’ve come across a few themes that didn’t quite make every line of text translatable. It almost drove me mad. Seriously. I was about ready to just punch my monitor. Thankfully another song came on and I was back to my calm self.

Functions

Yep, they do exists within WordPress. It’s actually quite nice that they do. Here are some that can be found in the includes folder:

  • __( 'I am a text string', 'theme-domain' )
  • _e( 'I am echoed', 'theme-domain' )
  • _x( 'Form', 'Art related', 'theme-domain' )
  • _ex( 'Form', 'Filing related', 'theme-domain' )
  • _n( 'Single', 'Plural', 'Number', 'theme-domain' )
  • _nx( 'Single', 'Double', 'Number', 'theme-domain' )
  • esc_attr__( 'I am an attribute', 'theme-domain' )
  • esc_attr_e( 'I will be an echoed attribute', 'theme-domain' )
  • esc_attr_x( 'Link', 'hyperlink', 'theme-domain' )

There are a few more but those are some of the ones I feel would be used more often than the others. In particular the first two. Those are by far the easiest ones to really miss. At least those are the ones I seem to find not being used when they should be.

What qualifies as a string?

When it comes down to it: anything that is inside markup. If it is wrapped inside an HTML tag then odds are it is a text string. A great example of this would be a very common line used by many themes. The “posted on” phrase. Now, there are several ways of doing this but I feel there are very few that are correct when it comes to translation strings.

$phrase = 'Posted on %s by %s';
printf( $phrase, get_the_time( get_option( 'date_format' ) ), get_the_author();

As you can see from the example I’ve provided it is a simple phrase that can easily be translated. The only thing you really have to do now is wrap the actual phrase with a translation function like:

$phrase = __( 'Posted on %1$s by %2$s', 'text-domain' );
printf( $phrase, get_the_time( get_option( 'date_format' ) ), get_the_author();

Fairly simple, right? But what about when it comes to numbers? That is what _n() is for actually. It’s a neat little function to use. It compares numbers! Yes, numbers. I love those things.

Okay, not literally compare numbers but fairly close. What it does do is actually determine which version of string to use. Sort of a juggling function with a twist. Really cool to use when you want to compare a single use, plural or even more.

A good example would be using it in a shopping cart.

echo "<h4>Items in cart</h4>";

$count = _n( 'Only one so far', 'Two items', get_total_items(), 'text-domain' );
printf( '<div class="cart-total">Currently: %s</div>', $count );

Pretty neat, right? I think so.

There are a few more functions to make translating a theme, or plugin, better but I feel those are the ones I find a bit more useful.

So you want to become a WordPress Theme Reviewer?

What does it take?

Some PHP, JavaScript, HTML, CSS knowledge and a little bit of time to spare. At least that is what it takes to get the ball rolling.

Yeah, very simple. Doesn’t take much really.

The basics

There are some things that you really have to know in order to becoming a WordPress Theme Reviewer. Here is a quick list I feel makes for a good theme reviewer.

  • Knowledge
  • WordPress prowess
  • Personality
  • Time
  • Communication

Now, that is what makes for a reviewer but how to get your foot in the door?

Those steps are a little bit easier. One of three ways to get started really. The first one is by requesting a ticket to review from the review queue. [note: it is as of this writing]

The second way is by emailing the theme reviewers mail list and asking if any new theme is available for a review. Keep in mind that you will have to subscribe to that list as well in order to keep in contact with all theme reviewers and admins. You can also follow a good few through twitter, personal blogs or however you’d like.

The third way, but is less frequently checked, would be through the IRC channel #wordpress-themes. They will also link you to the review queue I mentioned earlier so these last two would be just pushing it if you did all three. Just saying.

What next?

The next step would be to setup your testing environment. Getting all the needed information, the settings and finally testing the theme. How you set that up is entirely up to you but there are some things that must remain the same across all the testing platforms. Can you guess what that is? It’s a simple setting that will help solve some of your headaches.

It is setting WP_DEBUG to true in your configuration file. Yeah, a very simple thing, right? Keep in mind that there are other ways to keep track of errors as well.

As far as plugins go, there are plenty to pick and choose from. The widely accepted one is the developer plugin by the Automattic team. It is a great plugin to get you started in creating a theme or plugin.

Testing

Yeah buddy! Finally we can discuss testing the theme. In order to test a theme you need data. Enter the theme unit test file. There are a few places that have some sample posts and images that you can download. Just a simple XML file that you import. Thankfully there is one that is widely used by many theme reviewers. The file stays up to date and is looked over every once in a while for errors.

An alternative is to use your own posts if you have enough. I may one day try creating my own little set of posts but for now I use the theme unit tests provided. It’s convenient if you are just starting out.

Unit Testing

Simple. Follow the steps provided in the theme unit test page and then report any major errors in the theme’s ticket.

Go through each scenario and make sure you write any, and all errors that you encounter. Keep in mind that is only part of a review. There is one part that I feel is extremely important. Communication.

Let’s talk about it

Yes. Talking is the single biggest thing when you are reviewing a theme. Without talking to the theme developer neither one of you is learning or even progressing. I mean it. Keeping in touch is the key to becoming a good theme reviewer as well as a developer.

A great example of this would be a ticket I reviewed nearly four months ago. I assigned myself the ticket, looked over the code, tested to see if anything would break and took note of it all. I posted the required things that needed to be addressed in order for the theme to be approved.

I didn’t hear any response from the developer in three days. I posted a question asking if they needed more time. Still no response. Nearly a week later I told that person I had to close the ticket and not approve the theme. About a week ago I was on the support forums and saw that somebody had a question about the theme and if there would be an update, if any. Made me sad to see that.

Personality?

Yes. It does take a certain personality to be a good theme reviewer. At least I think so. The reason I say this is because as a theme reviewer you are helping somebody. You are helping them share something with the world. I know it does sound a little cheesy but it is true. Think back to when you were in school and you had to create something for a class project. Odds are there was at least one person in that classroom that got all the recognition and all the praise for going above and beyond what the project asked for.

Now put yourself in their shoes ( if you weren’t already that person ) and think about how it feels. It feels good. It makes me happy approving a theme. At least one that I feel is worthy of approval but that’s another topic.

Think you can?

So, you ready to become a theme reviewer? If so, then head over to the Make Theme blog, give some input, ask for a ticket and give back to the community!

Choosing the right path

It’s no secret that I love using WordPress and love design. Those are pretty obvious if you’ve known me for some time. I guess you could say I’m a little addicted to WordPress. My digital meth if you will, but I also love design about the same.

Working on WordPress themes is an amazing middle ground for me. It’s almost a zen state for me when I’m looking at a design and trying to figure out how to code the theme. Some themes require a little more TLC than others. A great example is when you have to think about the end user. As some may, or may not, know I like to help out in the WordPress.org support forums when I can.

I’ve even written a post about creating a child theme. Yes, I do encourage that in the forums as well if you want to make any modifications to any theme. The downside is that often times some themes don’t generally like to use: get_stylesheet_directory_uri()

Dilemma

Now, there are two things to remember when it comes to working with child themes.

  1. Use them
  2. Code properly for them

What I mean by number two is that you should be using the right function when it comes to enqueuing the stylesheets and scripts. In this case I’ll be talking about stylesheets.

A few days ago I was typing out some code for my theme and started to think about the structure of my folders. The most commonly used in themes seems to be to have all the CSS files bundled together and all the JavaScript files together as well. Simple and makes sense really. The downside is when some people use a stylesheet that resides in that folder. It does seem a little odd but it will all make sense in a bit.

The issue is when a parent theme uses the rule

@import url( 'path/to/stylesheet.css' );

in the main stylesheet. What that means is that the user now has to look for the location of the main stylesheet and create the right code for it. Or better yet have to include the

@import url( '../path/to/parent/stylesheet.css' );

rule in the child theme.

Why not make it a little easier for them?

How?

By using a quick conditional check to see if the current theme is a parent theme or a child. Yes, there is a function for it. Believe or not it is actually:

is_child_theme()

Simple little function that checks to see if the stylesheet path and the template path are the same; if they are then it is a parent theme, otherwise it is a child. Quick and painless, right?

But how to use it to our advantage? Easy. When we register our scripts and styles we add on the little conditional and when it is a child theme we use both the child’s stylesheet as well as the one being used by the parent.

if ( is_child_theme() ){
    wp_enqueue_style( 'parent-style', get_template_directory_uri() . '/css/mite.css' );
    wp_enqueue_style( 'child-style', get_stylesheet_uri() );
} else {
    wp_enqueue_style( 'parent-style', get_stylesheet_uri() );
}

You’ll notice that I am using two different functions when it is a child theme to enqueue the stylesheets being used.

The main reason for this is that when the function

get_stylesheet_uri()

is used it will get the location of the stylesheet of the active theme. We don’t always want that because if you are the a developer that likes to group their files accordingly then it may just lead to a little trouble.

With that little snippet you can now rest assured that when you activate the theme it will load the right path. Now in order for all of this to work we just add one minor thing to our style.css file:

@import url( ../css/theme-style.css );

Fairly straight forward, right?

Filtering the page links

Nothing is ever truly perfect. There are some things that do come close though. In the mean time we can make just a few changes to get our desired result. The photo above is a quick comparison of a photo I took a few years back while at Yosemite National Park.

As you can see there is a huge difference between the two. One is more vibrant and full of color while the other is just a little flat with little to no contrast. Yeah, I critique my own photos constantly. The left is the raw untouched file taken with my camera and the right is the edited version. As you can see it made it better by correcting some color and adding a little more light to the overall image.

Now, in WordPress one way of altering is by using filters. Recently I’ve been messing with one in particular that I feel can be a good practice for any theme developer. Filtering the arguments of wp_link_pages() to style post pagination.

Pagination?

Yes, pagination in posts. Often times when a tutorial or a written work is far too long that it needs to be divided into segments of easy to read, easy to consume blocks of text. In WordPress the

<!--nextpage-->

tag is used in the text editor to create another page within that post. WordPress handles this in one of two ways. The first is by listing the pages and the other is by using simple next/previous links. All themes tend to style that in different ways. The default Twenty Thirteen handles it like:

twenty-thirteen-link-pages.PNG

The way it is styled uses the same code throughout all the content related files. The reason I say it that way is because 2013 has support for all the post formats available within WordPress, which is amazing! Now the downside to that is that it can mean you have to copy/paste, type out a lot more code than you’d want to. I know I can be that way. I just want to be able to set it once and be done. I mean who doesn’t, right?

So, the way 2013 is coded is by calling wp_link_pages and then passing to it an array with some settings.

 wp_link_pages(
        array(
                'before' => '<div class="page-links"><span class="page-links-title">' . __( 'Pages:', 'twentythirteen' ) . '</span>',
                'after' => '</div>',
                'link_before' => '<span>',
                'link_after' => '</span>'
        ) );

As you can see you would copy and paste that code on all the files depending on how you have all your content files setup. While it does create that nice little HTML structure for us to style it may be tedious to have to copy and paste over and over. I know I got tired of it.

Solution

What I did was looked at the source code for the function. I took notice at one particular line of code that made me happy. That line was:

$r = apply_filters( 'wp_link_pages_args', $r );

The reason it made me happy was because I realized that I could filter the arguments and not have to type out all that code over and over again or even have to copy and paste it all. So all I now had to do was create a callback function and hook it through a filter.

add_filter( 'wp_link_pages_args', 'theme_link_pages_args' );
function theme_link_pages_args( $args ){
    $args = array(
        'before'           => '<div class="link-pages">Page ',
        'after'            => '</div>',
        'link_before'      => '',
        'link_after'       => '',
        'next_or_number'   => 'number',
        'separator'        => '<span>',
        'nextpagelink'     => 'Next Page',
        'previouspagelink' => 'Previous Page',
        'pagelink'         => '%',
        'echo'             => 1
    );
    return $args;
}

*If you are going to filter the $args make sure you use all the settings or you may end up getting some errors.

There we have it! Keep in mind that if you want the theme to be translation ready don’t forget to add the proper functions where needed and prefix the function with your theme’s name.

Twenty-thirteen in April

At least that is the plan from the development blog on core. I updated my trunk version on my desktop which I use primarily for testing and will be using for all my theme and plugin development needs.

The one thing that just about everybody noticed from the get-go was the color usage. Vibrant and a good color scheme as well. The one thing I don’t like is the way it presents itself on wider screens. Part of that reason is the content doesn’t take up much real estate and is centered. When I’m using my 22 inch monitor it does look really strange to see a band of color stretching from left to right.

The focus on this theme is post-formats. I’ve wanted to experiment with that for some time now ever since I learned about them. The best part about it is that with 3.6 launching the focus is also post-formats. Themes should be pretty interesting to see on how they style each one should they choose to. I have a few ideas on how I want my theme to look once I’m done – whenever that is. I’m tempted to just do text and call it a day; do it all in one file.

Looking over the files for the theme and I notice a few different things from previous bundled themes. One of the first things that I noticed is how few lines of code there are on the index file. Only thirty-eight lines and of those seventeen are comment/documentation. I still have several other files to look over and read to get more familiar with the theme.

I am tempted to create a child theme and use it on my personal site. So many ideas! I still have to take several pictures for the theme I’m creating so I can submit it to the WordPress repository. I think the challenge there will be keeping up to date and maintaining the theme as up to date as I possibly can.

Twenty-thirteen has a lot of promise and a lot of potential to it and I think it can derive some really cool themes down the road with a few tweaks here and there.

Learning with practice

The progress of my theme is decent. I have been learning how to work with Git and SVN more and more. I did recently have a little conversation with @ipstenu on Twitter about learning version control. Yes, I am still learning how to harness the power of simple commits and getting the hang of how to use branches and tags.

Which brought me to my main point: tutorials.

People on the web have dozens and dozens of them. Some are better than others and some are just beyond outdated. I was looking for a tutorial on how version control works using SVN. You would think I would find at least five. No. I found links talking about how SVN works but no real tutorial.

@ipstenu asked me if I could find one noob friendly tutorial. Of course I couldn’t. True, there wasn’t one. Yet. I have been contemplating creating a simple tutorial on how to use TortoiseSVN in a local setup. Sounds simple, right? Yes and no. The writing is a simple thing but taking all those screenshots to go with that will be a task in itself. I know I’m capable of it I just now have to find the time. Keeping in mind that even my current knowledge is not that great but it should suffice for the time being.

One of the first things that I learned was ‘commit’ so of course that will be the first topic. Next in line is ‘branches’ and ‘tags. and how they work. That is one thing I still haven’t yet mastered through a GUI. Just takes me back to when I was in Junior High and learning about computers but that is another story.

Yes, tutorials have helped me understand certain things but often times I don’t really learn unless I put forth the effort. Learning by practice is a great method and a great way for me and others to learn as well. I just hope that I can get my tutorial written out so that people understand. Although this has given me an idea for a future post: translation.