Add a Repeating Text Field to Options Framework Plugin

Options framework repeating field

Options framework repeating field
This is what we’ll be building.
I don’t hardly even know why I was working on this today.  Well a friend wanted to be able to control the radio buttons in a metabox, from the backend (since the otherwise brilliant WP-Alchemy is all dev-level coding) and for some reason  my brain went to theme option.  He ultimately went a different route and used Advanced Custom Fields.  But some days I just feel like not working and doing something fun, and the question of repeating fields in the theme options piqued my interest.  I asked Devin Price if his awesome Options Framework plugin has such a thing and he replied that no it didn’t exist…. yet. He wasn’t sure it was possible, which is like the worst thing to say to me. Of course it is possible! And now instead of working on something responsible, I will now solve this riddle. So I started digging into Options Framework. At first I thought that I would fork OF, but it turns out that all the functions/filters needed are already in place!   Wherever you have your $options array in your theme’s options.php to get a repeating field you’d define your custom option like so:

Then to handle all the parts of displaying this, scripting the repeat, and validating the data you’ll need the following group of functions, added to your theme’s functions.php.

Creating the Output

First, we need to output something when Options Framework gets running and encounters the custom option of type ‘repeat_text’. Devin has a catch-all filter already built-in, so we just have to attach a function to the {$option_type}_option_type filter, in this case repeat_text_option_type. This callback will create the input box (as many as needed by the array of values) plus one hidden one. It also creates the “Add New” button and for good fun we’ll throw in delete buttons next to each input. The markup (and later the script to handle the repeat) draws a lot of inspiration for WP Alchemy’s repeating groups.

Sanitation and Saving

Options Framework won’t save anything unless the data gets run through a sanitization filter. The neat thing, is that if you set up the input names as name="somefield[1]" and so on, WordPress will automatically save all the “somefield” fields in an array. So we just need to rifle through the array and sanitize each text field. We can do this quickly with array_map. Next

Style and Scripting the Repeating Fields

Finally, all the bells and whistles. What good is a repeating field if it doesn’t, you know, repeat. Again, I have to credit Dimas Begunoff for his WP Alchemy class. I’ve simplified some of what he was doing in metaboxes, by merely adding a data-rel to the hidden input. Then a few quick on handlers for the button click events and that hidden input we created earlier gets cloned and given a proper name attribute. Clicking a delete button, removes it’s associated input from the DOM.

Output

Because we’ve saved an array of data the if you try to echo out the results of of_get_option('example_repeat'); you will get Array. You have to loop through the array to print out each on individually with a foreach loop.

This is definitely beta-ish. For instance, I know it doesn’t take into account a way to set an array of defaults… like if you wanted to have two fields set up as the default. Maybe it is Google Chrome, but I’m also having a little issue with tab indexing. And finally… there was something else, but my mind just went blank. Get the full code from my Gist. As beta code, I am totally open to suggestions and improvements, but I won’t be able to help you set this up on your own sites. I’m just putting it out there for information purposes only. What would you use a repeating field for in theme options?

WordPress Filters Fundamentals

Ok, so you’ve read my previous articles on PHP basics and how to use WordPress action hooks. Now you want to play with the big boys and girls and try your hand at filters. Just a reminder that you are still essentially learning a new language. Be patient with yourself. It took me close to a year to really understand filters, so if I can help you learn it quicker than that I’ll consider this a successful article.

In my discussion of hooks and functions I have described the system of hooks in WordPress as being similar to a parking lot. The hooks are like spaces, the cars are like functions that can be parked anywhere and can be moved around. To expound on this metaphor, (or to beat it to death) I think a filter is similar to changing something about the car while leaving it in the same place. A filter is like a magic function box that takes a value in ( remember I talked about parameters in by Basics tutorial ) do something with it and send it back. So you have a red Porsche on the lot, send it to a filter and it might become a blue Porsche. Or a black pickup truck. Whatever. But it will still be parked in the back, 2 spots from the end.

When browsing WordPress core, themes and plugins, you will be alerted to the availability of a filter by the appearance of the apply_filters() function. In generic terms it will look like so:

It might look like:

or:

or even:

Parameters for the Filters

But I repeat, the big tip off is the apply_filters() function. The apply_filters() function can take an unlimited number of parameters but only the first two are required. 1. The first is the name of the filter. I was very confused early on because the Thematic framework tended to name the filters the same thing as the functions that contained them. And then in the one instance where they were different, I couldn’t get my filter to work for anything. I swore and threw things, cried and probably shaved a few days off my life from the stress. Turns out their sharing names was a convenience factor that makes a lot more sense to me now. So, just remember that first parameter is the filter’s name. 2. This is an important one, because this parameter is the variable that your function will receive. This is the value we’re going to change. This is the red car that we will turn blue. 3. This it the priority. Just like with adding functions to hooks, this controls the order that filter functions will be applied should there be more than one. The default is 10, so if you need your filter to run before that you’d use a lower number. This is rare, and usually you need to run your filters after others, so you’d want to use a higher number. In fact, until you are sure that you are conflicting with another function you can pretty much just leave it at 10. 4+. These are other variables that might give you some useful information for manipulating the variable getting filtered. Remember we talked about scope in the PHP Basics. Instead of declaring these globally and hoping they arrive intact, WordPress will send your filtered variable along with some friends.

A Filter with Training Wheels

In super generic terms let’s take a look at the basic set up for filtering.

The structure is almost exactly the same as that for add_action(). In reality, we are adding an action, just of a slightly different type: one that modifies a specific variable’s value. One thing to note here, is the number 2. This is the number of parameters that you are passing into the function. You’ll always pass 1 variable ( ie. the variable that you are filtering ) and in this case you wouldn’t even need to declare it. That’s the default value, just as 10 is the default value for #priority. However, some filters provide access to other variables (like our fake $other_arg), and if you want to use them in your filter function then you have to name them inside the parentheses and then write the correct number at the end of the add_filter() statement.

If you have 2 parameters in the function, but don’t have the number 2 at the end of add_filter() you will get White Screen of Death. If you have the number 2, but don’t declare two parameters, guess what, you will also get WSOD. So make sure your parameters match up. And you absolutely, must, sans doute, return a value. If you do not, that is essentially the same as returning a null string. If you echo something here, it will likely not appear where you expect it, so don’t. RETURN, RETURN, RETURN.

Remember in my PHP basics I talked about two functions playing catch. The return statement, is you throwing your modified version of the variable back to the apply_filters() function so that WordPress can continue on its merry way, but using your value now.

You’re a Real Boy Now, Pinocchio.

A Real Filter If you’ve managed to read all this, then… well… Bless you. I want to end on a real filter that you can drop into your theme’s functions.php and actually see a working result.

Not too shockingly I am using Bacon in my testing code. If this bothers you… well, its not real bacon and you may use whatever you wish in your own tests. WordPress has a filter called the_title() that lets you modify the title of every post! As written above it will literally add BACON everywhere the_title() is called. Bacon everywhere, all the time has its appeal, sure, but I will whet your appetite with some neato WordPress conditional logic that will only add Bacon to the titles in the main loop, and only on the front-end.

Conclusion

I hope that helps things make more sense. Remember, THIS IS HARD!! Do not be discouraged if you don’t get it right away. I cannot provide specific support in the comments ( Hire Me, instead! but do let me know if there are places where I could be more clear.

Nav Menu Roles Plugin

Over the weekend I was working on a project and my client needed to be able to hide certain menu links from non-logged in users.  In the past I have just created 2 menus, one for logged in users, and another for logged out users.  Not the most convenient thing ever, but simple enough.  However, since this was at least the second, and possibly the third time this has come up in various projects I decided to dig further.

Adding fields to the menu item back-end

This was the trickiest part really, because there aren’t any action hooks in this part of the code.  I have requested one with the following Trac Ticket, but until that gets added to we have to do it in a slightly less efficient way.

Thanks to this WordPress Answer I found that the whole menu item form is created by the Walker_Nav_Menu_Edit Walker, but that tucked away in the code is the ability to filter this and send a new Walker via the wp_edit_nav_menu_walker filter.  Actually this answer got me about 80% of the way there so I can hardly claim to be clever or original.  I just packaged it up.  Couples with this Answer about front-end menu Walkers, the first beta draft of my plugin was born.  At this point it really only handled different roles.

Nav Menu Roles screenshot
New options for menu settings allow you to customize who can view particular menu items

Before it was even added to the WordPress repository, Pippin Williamson did a quick video review, so I guess I am not the only person who has needed this ability from WordPress.  Pippin also had the cool idea to add the ability to show an item to all logged-in users, or all logged-out users, so the video screenshots will look different from the end result of version 1.0.  I think this was a cool addition, so thanks Pippin for the idea and for helping me work on it.

Basic Usage

Install and activate the plugin like normal. Create a custom menu and add items to it just like you usually would. You will now see the extra fields shown in the screenshot. From here you select to show the item to all logged in users, all logged out users… or to customize by role. If you chose customize by role, then you can use the checkboxes to determine which roles should be allowed to see this particular menu item. If you choose customize by role and do not check any roles, then the item will show to everyone just like it used to. There isn’t any more to it than that. It should be pretty straight-forward.

Download

Now available in the WordPress Repo.

Also available via my Github repo.

Support

Support is limited to bug-fixing and basic implementation. I can’t help with any customization.

Please report any bugs at Github’s issue tracker.  

Support requests are best handled in the Support Forums. Please don’t post support questions in the comments!

Enjoy! And let me know what you think.

Absolute PHP Basics for WordPress Newbs

“I’m just a designer. I’m comfortable with CSS but PHP scares me.” Yeah ok, well first off, if you are a designer…. instead of banging your head into a wall to learn a coding language, why not hire a developer? Some of my best clients have been designers. It is kind of a win, win. I get to work on pretty sites and you get to do more designing and less stressing. Send me an email and let’s see if I can help. But if you insist on trying to defy your right-brained designery nature and become more left-brained here are a couple of points that I think will help you as you try to learn both PHP and its sub-dialect of WordPress.

Function Function What’s Your Function

Functions do things. Ever learn about functions in middle school math class? Magic black-boxes where numbers go and come out as something else? Well it is pretty much the same. Let’s start with the simplest function possible, a nice spin off on the classic hello world().

But not all functions echo out a value because we don’t always want to echo (which is just another way to print something) a value out right away. Sometimes we need to process it more, etc. In that case you’d return a value. Returning a value is just the opposite of echoing a value. It says, don’t print it right now, save it for later.

To print it later we’d have to actually echo out the function.

or

See what we did there in that second one? We defined a variable, which if you’ll remember from math class is a bit of an amorphous blob that can have any value. Then we set that variable equal to the value returned from the hello_bacon() function.

Getting into Arguments

The hello_bacon() function is obviously super simple. It always returns the same thing. Well that’s not so much fun and sort of defeats the purpose of a function. Remember those magic black boxes? Well now we want to take a variable in, manipulate it and spit it back as something new and shiny. We send variables into functions as arguments to that function.

As you can see above, the favorite_food() function accepts 1 argument. Inside of the favorite_food() function this argument will be referred to by the variable $food. This sort of touches on a concept that we’ll get into in a bit, called variable scope. But for now remember that $food does not exist outside the favorite_food() function.

If you need to ensure that you never get an empty value for “My favorite food is ____” then you can give an argument a default. If you don’t pass an argument when calling a function it will simply use the default. Note below that ‘bacon’ is the default value of the $food variable.

By now you might have noticed that we’ve only been dealing with what are called, ‘string’ variable types…. words or letters essentially. You’ve been seeing me combine strings together with a period (.) in what is called string concatenation. But just like math class, PHP functions work on numbers.

Variable Scope

Whoa hold up! You just said the argument was called $x, but there you go calling it $a. Yup. Remember when I said it was important to remember that variables (usually) only exist inside the function where they are defined. That is what is called variable scope. In PHP and WordPress you can declare variables as global in scope, meaning $x has the same value everywhere, but by default variables are local in scope, meaning again, they only exist within the functions using them. I could rewrite the above to be:

I can call the variables anything I want, because the $guacamole in the double_it() function is not the same as the $bacon outside of it. Remember variables are placeholders. Think of it like the two are playing catch. In the following line:

We are passing a value to the double_it() function. The function then catches the value as its argument.

Now the variable has a new name, but the same value. In the example the value was 10, that part isn’t any different. Within the function the variable $guacamole now has a value of 10. Then it performs its multiplication and sends back the doubled value. The is the pass back.

And that brings us back to:

where the variable $bacon catches the return pass, and the variable $bacon is now equal to 20, which we see when we echo $bacon. So it is like playing catch. If you are out in the yard playing catch with someone who doesn’t speak the same language as you and you toss the ball to your partner, when she catches it, she might call it a beisbol. When she throws it back to you, it is a baseball again, you both just had different words (variables) for it. This is the official PHP manual that might help explain things if my metaphors made it clear as mud. http://php.net/manual/en/language.variables.scope.php

In Summary

We covered functions, function arguments, string variables, numeric variables and variable scope. There is quite a bit more, but I already feel like this is a lot actually and hopefully you are well on your way to programming hell… I mean bliss. Please point out any errors or places where I could be more clear, but keep Thematic and WordPress specific questions for their respective forums. Best of luck.

Radio Buttons for Taxonomies

Radio Buttons for Taxonomies!
Radio Buttons for Taxonomies! Unfortunately the subject can no longer be both guacamole and bacon. You’ll have to chose.

Every now and then I run across a client who needs a taxonomy where the user is restricted to only allowing one term per post.  I’ve also seen people wanting this a few times for categories, and I, myself, have wished for it a few times.  Sometimes a post needs to be like a piece of paper in a folder… and only be in 1 dang folder at a time.  Some might argue that categorization with a single, exclusive term is more-suited to post meta, and they might be right, but the ability to list all the existing terms is lacking from a post meta implementation.

So, the problem is checkboxes… checkboxes let users check more than one box.  So, the solution is then radio buttons!  Which enforce a single selection.  There are a few tutorials floating around on the interwebs on how to do this.

Hands-down, the best tutorial on radio buttons with taxonomies was written by Stephen Harris, so I owe him a huge debt for providing most of the guts of my plugin.  His OOP class implementation allowed you to define some variables, such as taxonomy and post type… and the class would do the rest, but only for a single taxonomy.  Well the whole point of OOP-style programming is that you can re-use it!  I set about building a standard plugin container with a settings page where you can check which taxonomies you’d like to convert to radio buttons.  I would then create a new object based on each of these taxonomies.  So I had to tweak Stephen’s class so that I could use it to create new objects (basically just switched his load method to __contruct() and pass those objects a parameter, namely the taxonomy.  I scrapped the other parameters.   The div id will just be standardized based on the taxonomy and the metabox will be changed for every post type that uses a particular taxonomy.

Radio Buttons for Taxonomies settings configuration
Now it is super simple to convert any taxonomy to radio buttons

Installation Instructions

  1. Install Plugin
  2. Activate Plugin
  3. Go to Settings>Radio Buttons for Taxonomies
  4. Check which taxonomies you’d like to convert to taxonomies and click Save Changes

Literally, that’s it.  And now when you return to your edit your post you will see the new metabox.  Hope you enjoy!  I have a few ideas for improvements, such as better error handling when you try to add new terms and getting radio buttons in the quick edit, but this should get you started.

Download

Download from the official WordPress Directory

or you can track, contribute to the development, or fork me at at Github.