ArtistDataPress Expiration

In case you haven’t heard, ArtistData is shutting down. Since AritstDataPress merely re-displays the feed from ArtistData, the plugin will also be shutting down. The final date is October 14.

I recommend checking out either BandsInTown or GigPress. BandsInTown covers the online service bit; GigPress keeps everything on your site. I’ve seen good results from both, so you can’t lose.

How to Add a Select Menu of Formidable Forms in Customizer

I recently had a need to list all the published Formidable forms as a select control in Customizer. Formidable doesn’t spell out how to get this list, but I eventually stumbled on this method.

$forms = FrmForm::get_published_forms();
$choices = array();
foreach ( $forms as $form ) {
$choices[$form->id] = $form->name;
// Formidable Forms Select Field
'capability' => 'edit_theme_options',
'default' => '',
'transport' => 'postMessage',
'type' => 'theme_mod'
'active_callback' => '',
'choices' => $choices,
'description' => esc_html__( '', 'text-domain' ),
'label' => esc_html__( 'Formidable Forms Select', 'text-domain' ),
'priority' => 10,
'section' => 'your-section',
'settings' => 'formidable_form_select',
'type' => 'select'
$wp_customize->get_setting( 'formidable_form_select' )->transport = 'postMessage';

Brief explanation

Use the get_published_forms() static function in the FrmForm class from Formidable to get an array of public form objects.

Loop through them and add each to the $choices array, which is used for the choices in the Customizer select control.

This control will return the form ID. You could tweak this to use the form key or any other data from the form object.

How to Link to the Customizer

I recently needed to link to a custom panel in the Customizer and had to figure it out. Devin Price pointed me in the right direction, but I ended up looking in the WordPress core to see how they do it and this is how.

This a simple link to Customizer:

<a href="<?php echo esc_url( admin_url( 'customize.php' ) ); ?>">Link to Customizer</a>

Linking to Panels, Sections, and Controls in the Customizer

If you want to link to a specific panel in the Customizer, you’ll want to use this:

$query['autofocus[panel]'] = 'nav_menus';
 $panel_link = add_query_arg( $query, admin_url( 'customize.php' ) );
 ?><a href="<?php echo esc_url( $panel_link ); ?>">Link to Panel</a>

If you aren’t familiar with add_query_args, its worth reading up on it. I learned about it from Fränk Klein for how to properly add Google Fonts to WordPress. Pippin Williamson also has a good post about write-up about using add_query_args too. We’ll see later how you can use it to create more advanced links into the Customizer.

One warning: always specify the URL parameter and always escape the output. The core developers discussed this issue in April of 2015. If you don’t specify the URL and don’t escape the output of this function, then someone might be able to use it as a XSS attack vector. If you’ll notice, I’m including the esc_url() function in the output of each of the examples above and the URL parameter is specified too.

In the $query array, the key is tells the Customizer what to do, then the value tells it where we’re going. The this example: autofocus in a panel called “nav_menus”. You can change the value to the panel of your choice. Here’s a list of the default panels included in WordPress (as of version 4.5.2):

  • widgets = Widget panel
  • nav_menus = Menus panel

If you want to link to a section instead, you can change part of the key:

$query['autofocus[section]'] = 'title_tagline';
 $section_link = add_query_arg( $query, admin_url( 'customize.php' ) );
 ?><a href="<?php echo esc_url( $section_link ); ?>">Link to Section</a>

Here are the IDs for the default sections in WordPress:

  • static_front_page = Static Front Page section
  • title_tagline = Site Identity section

Some of the default themes like Twenty Sixteen add their own sections and any theme can add the following sections by declaring theme support for them:

  • background_image = Background Image section
  • header_image = Header Image section

The real magic is linking to the customizer and autofocusing on a specific field (aka control):

$query['autofocus[control]'] = 'blogname';
 $control_link = add_query_arg( $query, admin_url( 'customize.php' ) );
 ?><a href="<?php echo esc_url( $control_link ); ?>">Link to Control</a>

This links to the Site Title field in the Site Identity section. If you’re asking people to go to a specific place and make an edit, go ahead and link this way to make it easier.

After the Customizer

In addition to linking to somewhere within the Customizer, you can also specify where to go after you exit. Core uses the page you’re currently on by default. You can check the link to the Customizer from different places in the admin and see that return value changes.

$query['return'] = admin_url();
 $link_with_return = add_query_arg( $query, admin_url( 'customize.php' ) );

That will link to the Customizer and return you to the Dashboard.

FYI, you cannot specify any old URL to go to afterwards. For instance, this does not work:

$query['return'] = '';
 $link = add_query_arg( $query, admin_url( 'customize.php' ) );
 ?><a href="<?php echo esc_url( $link ); ?>">Go to CNN after</a>

The Customizer runs these return URLs through the function wp_validate_redirect(). By default, the only allowed URL is the home_url(). Additional URLs can be added using the allowed_redirect_hosts() filter. The wp_validate_redirect() function is used for many parts of WordPress, so I’d advise caution when adding URLs to this allowed list.

Now, we can build more specific URLs for the Customizer. This could be especially useful if you’re walking a site admin through performing several steps:

$query['autofocus[control]'] = 'blogname';
 $query['return'] = admin_url( 'post-new.php' );
 $link = add_query_arg( $query, admin_url( 'customize.php' ) );
 ?><a href="<?php echo esc_url( $link ); ?>">Set title, then write post</a>

This links into the Customizer, autofocuses on the Site Title field, then once you’re done, takes you to the new post page.

Set the Preview Page

If you have Customizer controls that only apply to specific pages, you can specify which page appears in the previewer:

$query['url'] = site_url( '/news' );
 $link = add_query_arg( $query, admin_url( 'customize.php' ) );
 ?><a href="<?php echo esc_url( $link ); ?>">News Page in Preview</a>

In this case, the Previewer will display the News page instead of the home page. I’m planning to do additional testing to see if this could be used to style a plugin-specific page.

All Together Now!

Those are all the parameters currently available for the Customizer. Now you can get really crazy (and specific) about your links to the Customizer. For example, go to the Menu Locations, show the About page in the previewer, then when you’re done, add a new page:

$query['autofocus[section]'] = 'menu_locations';
 $query['return'] = admin_url( 'post-new.php?post_type=page' );
 $query['url'] = site_url( '/about-us' );
 $link = add_query_arg( $query, admin_url( 'customize.php' ) );
 ?><a href="<?php echo esc_url( $link ); ?>">Craziness!</a>

To wrap up, there are three parameters you can use to link into the customizer: return, url, and autofocus. Use add_query_arg to build the URL and esc_url to display it. You can use the autofocus parameter to focus on a panel, a section, or a specific field. You can use the url parameter to display a specific page in the Previewer. You can use the return parameter to go to a particular place after going to the Customizer. Happy linking!

Here’s a gist of all the code, if you prefer that.

How to Change the Featured Image Labels

When creating a site for a client or creating a plugin, I’ve found its helpful to customize things as much as possible to the intended usage. This is especially important for client work since most clients have an internal language, or terminology they use for things. In the case of Featured Images, the site or plugin might be using the featured image differently than how one might use it on a news or blog post.

I’m currently writing a plugin with a custom post type and using the featured image as a headshot for an employee. While “featured image” may work fine, “headshot” is more specific and makes more sense in this context. I haven’t been able to find anything recent about how to change the labels on the existing Featured Image metabox. The most commonly referenced code only works some of the time. Specifically, when one removes a featured image, the label for the link changes back to referencing “featured image” instead of the customized label.

I dug through the core and found the post_type_labels_{$post_type} filter, which was added in version 3.5. This filter makes customizing the featured image labels super easy:

* Changes strings referencing Featured Images for a post type
* In this example, the post type in the filter name is "employee"
* and the new reference in the labels is "headshot".
* @see
* @param object $labels Current post type labels
* @return object Modified post type labels
function change_featured_image_labels( $labels ) {
$labels->featured_image = 'Headshot';
$labels->set_featured_image = 'Set headshot';
$labels->remove_featured_image = 'Remove headshot';
$labels->use_featured_image = 'Use as headshot';
return $labels;
} // change_featured_image_labels()
add_filter( 'post_type_labels_employee', 'change_featured_image_labels', 10, 1 );
view raw gistfile1.txt hosted with ❤ by GitHub

The labels are in an object and we then reset the values of each specific item to what we want. Then return the object.

Avoiding get_theme_mod Errors

If you’re getting an error related to get_theme_mod, its most likely from how you’re checking if the returned result is empty. Most developers will probably do the same thing I did: make a variable and assign it to the result of get_theme_mod. Then check if its empty using PHP’s empty() method. Sadly, this is where you’re getting an error. Instead, check if the result is equal to ”, or blank.

* Do this
if ( '' == get_theme_mod( 'something' ) ) { ... }
* Not this
if ( empty( get_theme_mod( 'something' ) ) ) { ... }

Using WordPress Plugin Boilerplate

This afternoon, I presented “Using WordPress Plugin Boilerplate” at WordCamp Dayton. My presentation covered the new 3.0 version of the boilerplate. I want to make everything easy to find, so here are the links from my presentation, including my sample plugin “Now Hiring”:


Sample plugin:

WP Plugin Boilerplate:




WordCamp Dayton 2015

I’ve been accepted to speak at WordCamp Dayton this year! I’ll be speaking on using WordPress Plugin Boilerplate. I’ve been using this for the past few months for all my plugins and found it be extremely useful and well done. I’ll be going over the basics of how it works, why you’d want to use it, and showing code for basic plugin things like widgets, metaboxes, post types, and plugin settings.

Look forward to seeing you there!

SimpleMap Shortcode Reference

I’ve been using a plugin called SimpleMap for clients recently. SimpleMap creates a custom post type for managing locations (think store locations) and displays a Google Map with those locations. It also uses Google Map’s radius search to help people find locations near them. Everything on the front-end is managed using a shortcode. Practically every setting in SimpleMap can overridden in the shortcode, which is really cool for us developers. Plus, they have tons of filters throughout, so any text or label can be customized for your usage. While the “Help” tab in the plugin settings shows you some of the options available with the shortcode, there are tons more and the documentation is practically non-existent. I’m putting this out there, at least for my own reference and I’ll keep adding to it as I learn more and/or have time to expand it.

The gist below explains how to use the shortcode and the more common attributes to use with it.

* Basic shortcode
* Hide the search result list
* @param bool true: hide the list
* false: show the list, this is the default
[simplemap hide_list=true]
* Hide the map
* @param bool true: hide the map
* false: show the map, this is the default
[simplemap hide_map=true]
* Hide the search form
* @param bool true: hide the search form
* false: show the search form, this is the default
[simplemap hide_search=true]
* Limits the search results list to locations from the specified category or categories.
* @param int A comma-separated list of category IDs.
* Do not put spaces between the IDs, just a comma
[simplemap sm_category=8] // one category
[simplemap sm_category=8,9,10] // mutiple categories
* Displays a checkbox for each category as part of the search form.
* Allows the site visitor to filter the search results by category.
* @param bool true: show the category filters
* false: hide the category filters, this is the default
[simplemap show_sm_category_filter=true]
* Specify which fields are included in the search form
* The search form is built in a table.
* Put "||" between each field.
* Here are the options for requesting a field:
* "labelbr_": puts the label with a break return tag afterwards
* "labelsp_": puts the label with a space afterwards
* "labeltd_": puts the label and field in separate table cells.
* "" (blank): puts no label, just the field itself.
* The fields that you can include are:
* street
* city
* state
* zip
* country
* distance: the select menu for the search radius
* empty: puts an empty table cell (useful for formatting the search form properly)
* submit: the submit button. If you don't include this, a hidden button will be added for you.searc
* taxonomy: include the filters for a specific taxonomy. There are four defaults:
* "sm-category"
* "sm-tags"
* "sm-day"
* "sm-time"
[simplemap search_fields=labelbr_street||labelbr_city||labelbr_state||labelbr_zip||labelbr_country||labelbr_distance]
* Changes the name of the search form.
* Default is "Find Locations Near:"
[simplemap search_title="Search this"]
* Changes the number of default table cells.
* Default value is 3.
* NOTE: This one doesn't seem to work for me.
[simplemap search_form_cols=4]
* Changes the field format for the taxonomies.
* Accepts "checkboxes" or "select". Default is "checkboxes".
[simplemap taxonomy_field_type="select"]
* Sets the default latitude. Default is "44.968684".
* Ideally, use with default_lng.
[simplemap default_lat="39.840315"]
* Sets the default longitude. Default is "-93.215561".
* Ideally, use with default_lat.
[simplemap default_lng="-88.954800"]
* Sets the map width. Default is 100%.
[simplemap map_width="60%"]
* Sets the map height. Default is 350px.
[simplemap map_height="300px"]
* Sets the measurement units.
* Accepts "km" for kilometers or "mi" for miles. Default is "mi".
[simplemap units="mi"]
* Sets the radius for the search. Default is 10.
* Use an integer and no unit.
[simplemap radius=12]
* Limits the quantity of how results are returned.
* Use an integer. Default is 20.
[simplemap limit=12]
* Quantity of results to autoload.
* Use an integer. Default is "all".
[simplemap autoload=12]
* Like most shortcodes, to add multiple attributes, put a space between them
[simplemap hide_list=true hide_map=true hide_search=true sm_category=8,9,10]
view raw simplemap-shortcode hosted with ❤ by GitHub

ArtistDataPress updated to v0.72!

Its been a long year. I’ve been trying to get back to ArtistDataPress and finally had a break in the schedule. So I resolved the larger issues people have brought up on the WordPress support forums. First off, if anyone feels I abandoned the plugin, please forgive me. Paid gigs come before free plugins. However, my schedule has freed up quite a bit now, so I should be able to make regular updates.

Version 0.72 brings the following changes:

  • BUG FIX: Resolved the “undefined function get_example_data()” error
  • BUG FIX: Removed the transient caching – causing too many errors and complaints
  • Removed “Custom” template option; added custom template explanation instead.
  • Changed Twitter account info
  • Added plugin icon to assets

ArtistDataPress is also compatible with the current version of WordPress, so there’s also that. Happy updating!

Inline SVG the Sane Way

Like everyone else these days, I’ve totally jumped onboard the SVG train. They’re scalable and easy to use. If you use inline SVG, they are style-able and reduce server requests, which can help your SEO.

Sadly, inline SVG also borks up your code. There’s nothing more disappointing than combing through neatly organized code thats completely marred by a giant block of inline SVG gibberish in the middle of it.

Recently, I discovered a simple way to have my cake and eat it too (mmm, cake!). Check this out:

Simple, right? The function has one parameter that determines which SVG is returned. While this one function may look out of control (although in my editor, each SVG is on one looooooong line, so it still remains neat and tidy), the SVGs and their craziness are contained to one place in your code.

This still gives you all the advantages of inline SVG, without borking up your nicely indented, organized code. In my next post, I’ll show how combining this with some other simple functions can give you inline SVGs in menu items!

As a footnote, the $output being initiated and returned outside the switch means there’s a fallback. If the requested icon isn’t in the switch, nothing is returned. You could do that with a “default” statement within the switch, but I’ve also found being able to append the $output variable is more dummy-proof that other methods.