Brace yourselves. Updates are coming…
Have you ever used register_field_group() for a packaged theme or plugin? Most people haven’t. In fact, http://advancedcustomfields.com doesn’t even have documentation on the function. Where this function comes into play is if you try to register a field group (and subsequently, fields) with PHP using the ACF API. The easiest way to see this is by using ACF’s built in PHP export. The subsequent block of code that is rendered can be pretty daunting, and in my opinion, a little bloated depending on your application. For people exporting fields for a theme, it’s probably fine, but for someone writing a plugin that dynamically creates fields, this behemoth can be a pain to write and manage. My biggest beef is with the “location” key passed to register_field_group().
“Location” accepts a multidimensional array, mapping each key => value to the boolean-esque rules that are used to assign fields to a particular location in your WP installation. For example, only show this field for this particular page and the user is an administrator. Where this get’s to be a little overwhelming, is when you are registering a field to a lot of different areas, yet ignoring a lot of others. One example I’ve used recently is widgets. I want to add a text field to all the default WP widgets but not all the other ones. My location value may look something like this:[gist https://gist.github.com/6edebde58013f429b0bf /]
You can see how that can start to get a little ridiculous right? 60 lines for one value? Especially when most of it is repeated! So I wrote a function for generating these giant location arrays when all the values are similar.[gist https://gist.github.com/ac2f976d8929c7bd18c2 /]
In a nutshell you pass an array of locations that all share a similar a similar parent. In the case above, they were all widgets. Then you supply the operator to compare against and an $extended boolean parameter. The $extended variable is for when each location is a new rule. For example, I want to show this field when the widget is “Archives” or when the widget is “Meta.” The default logic to show a field is that all the parameters must match (and operator). We then pass this function to a variable which we use with the location rule of register_field_group().
$locations = acfw_location_rules( $wp_widgets, 'widget', '==', true ); register_field_group( array ( 'location' => $locations, // rest of the function goes here ... ) );
Hopefully you find uses for this in your own projects. I know for me, it was definitely a lifesaver for generating long arrays for location rules. I will admit, not being able to set to parameter for something like both “Widgets” and “Administrators” is a limitation, but I’m working on an elegant solution for those instances.
Leave a comment below if you have any questions! I’d be happy to help! Check out http://reddit.com/r/advancedcustomfields if you want to be part of a community all about ACF.
Let’s say I’m building a theme for my client “Joey’s Frog Arena.” When I start development, I would namespace all of the theme functions with
jfa_, or something similar, and be on my merry way. This is completely normal. Everybody namespaces themes as to avoid conflicts and create a sense of coherence throughout the code.
Something that didn’t occur to me until this specific project was the idea of using a namespace for fields within ACF. So let’s say Joey has 3 different wrestling shows, all of them with 6 participants in each show, totaling 18 different participants. For the sake of simplicity, I’ll call them actors (everyone knows wrestling is fake anyway). So each show is listed as a custom post type, morning, afternoon, & evening shows, and the actors in each show change from week to week. Joey wants his customers to be able to visit the website and see a list of upcoming shows and who is participating in each one.
So I would need to attach a field to each show type that allows Joey to list out the actors for each show. Normally I would call this
actors and move on. In the code, I would call this in the template with
the_field('actors'); and everything would be handy dandy. Joey would be happy, I would be happy, all is good with the world.
Three months later though, Joey comes back to me and says he wants to add a widget to the homepage that spits out all the actors who are performing that day. So I would make a widget that uses some custom queries to pull of that information in and put it on the page.
|$args = array(|
|'post_type' => 'morning_show'|
|$actors = new WP_Query($args);|
|if ( $actors->have_posts() ) : while ( $actors->have_posts() ) : $actors->the_post() :|
|endwhile; endif; wp_reset_postdata();|
Pretty standard stuff right? Just do that 3 times for each post type with some extra stuff added as needed. I finish the feature, Joey pays his bill and I go back to working on other projects. Now let’s jump 1 year into the future.
Joey is back, and he wants some modifications done to the widget I made for him last time. Well, it’s been a year. I don’t remember any of this stuff. Now I have to sift through this code and find where these specific parts are coming from and alter the output of the functions.
ENTER NAME SPACING
Name spacing is a normal part of modern software development. It helps us to stay organized and provides a easy to recognize reference if we have to come back to something later and our documentation just isn’t cutting it. Recently I’ve found myself name spacing all my fields with the name of the field group. This obviously means that choosing the right field group name can be very important! For Joey, I would have had 3 field groups, Morning Show, Afternoon Show, and Evening Show, since those were the 3 post types I was adding fields to. So for the actors field, I would set the label as “Actors” as normal, but the field name would be “morning_show_actors” instead of just actors. Let’s say I had another field called “Location.” That field name would be “morning_show_location.” I hope you can see where this is going.
If I was utilizing a large template to display data from custom queries, I don’t want to have to scroll up and down my document to see what post type I was referencing for a specific field. By including the field group as a namespace, I know exactly what information I’m working with no matter where in the theme I’m using it. This also means I can use a “Find All” in my IDE and search for “morning_show_actors” and only get the one result I want, rather than 3 results for the search term “actors.”
Hopefully you can see the benefit to name spacing and will start to utilize it on your projects. Sure, it’s a pain in the ass to manually alter each field name instead of using the generated name from ACF, but a year or two down the line, you’ll be happy you did when you can’t remember the specifics from a given project.
P.S. After reading this blog post, I’m very disappointed in myself, but I’m putting it out there anyway, despite it’s sloppiness. Oh well. 😉
Advanced Custom Fields (ACF) is a plugin that adds easy access to creating, editing, and maintaining custom meta boxes and fields to WordPress. Using a very simple API, developers can show the values of these custom fields on the front end of by editing theme template files. The official ACF site has a lot of awesome documentation to show you how to use almost every feature included in the plugin, but today we are going to go a little further. Let’s take a look at adding custom profile fields to users in the backend and create a way for logged in users to edit that information without going to the dashboard.