WordPress 3.6: shortcode_atts_{$shortcode} filter

Since WordPress 3.6 is in beta, I thought I’d use this nearly-abandoned blog (hey, been busy working on WordPress!) to talk about some of the cool stuff for developers. For the first installment, check out the new shortcode_atts_{$shortcode} filter. The shortcode_atts() function now accepts a third parameter — the name of the shortcode — which enables the running of this filter. All of the core shortcodes now pass this parameter.

This filter passes three things:

  1. $out — the output array of shortcode attributes
  2. $pairs — the array of accepted parameters and their defaults.
  3. $atts — the input array of shortcode attributes

Let’s look at what we can do with this. One thing is that you can dynamically set or override shortcode values. You an also define new ones, and transpose them into accepted ones. Let’s look at the “gallery” shortcode for example. What if there was a gallery of images that you would reuse. Instead of picking the images each time, you could have a plugin that gives that set of attachment IDs a shortcut name. Then you could do [gallery foo=my-gallery-name], which the plugin would convert to a list of IDs. Or, you could enforce a certain number of gallery columns on the fly. Let someone set it theme-wide, without having them go back and change their shortcodes.

What other uses can you think of?

Now, if you’re a plugin or theme author who provides their own shortcodes, you should immediately start providing this third parameter to your shortcode_atts() calls (since it is an extra parameter, you can do this without a WordPress version check). Maybe it’ll reduce the number of times people need to fork your code just to add an option to your shortcode!

24 thoughts on “WordPress 3.6: shortcode_atts_{$shortcode} filter

  1. That’s a subtle feature, but something that could prove invaluable in many situations. Thanks for posting about this.

    You may not post often, but we always appreciate it when you do 🙂

  2. Thank you, Mark, for the post.
    Could you explain how to use it on simple example?
    How the next code should be changed to provide this third parameter?

    function pagelist_shortcode( $atts ) {
    extract( shortcode_atts( array(
    'depth' => '0',
    'child_of' => '0'
    ), $atts ) );
    $page_list_args = array(
    'depth' => $depth,
    'child_of' => $child_of
    $wp_list_pages = wp_list_pages( $page_list_args );
    return ''.$wp_list_pages.'';
    add_shortcode( 'pagelist', 'pagelist_shortcode' );

    1. Just to clarify: this means users can potentially add a custom filter for pagelist and change the $atts? Will they need to specify all the values such as ‘depth’ and ‘child_of’ when filtering or can they just pick e.g. child_of if depth’s default is to remain 0? Thanks 🙂

  3. What other uses can you think of?

    Themes can now customize the caption width and don’t have to accomodate for the extra 10px that are added by default.

    Twenty Thirteen uses the filter to increase the image size for its featured gallery in the Gallery post format.

  4. Yays! I can use that when I finally update my Fancybox Gallery plugin. I need to override the default image linkage to be directly to the file, instead of to the attachment info page.

  5. Oh sweet. I have a plugin I made w/ a filter to adjust stuff globally w/o having to specify an override each time the shortcode was used since there were also defaults. This will be a much cleaner way to target and do that. Thanks Mark!

  6. Not related to this blog (sorry) but need urgent help. I have quite a few categories, sub, categories & sub sub categories which makes navigation difficult when the cursor hovers over categories & makes many sub categories jump open. Is it possible to make it so sub categories don’y drop down unless clicked upon. Thanks very much

  7. Looks like a very useful feature ! That’s what I love about WordPress ! It becomes always easier to override the defaults and have it all look exactly as you need !

  8. I’m not really good with the technical aspects of blogging, but thank you…. for you are one of those people do their best to keep things running as smooth as possible… 🙂 by the way, I love the WP badges for your header! thank you for keeping us informed….

  9. Most useful when dealing with custom thumbnails using WordPress Core galleries.


    function yourfunctionname_gallery_atts( $atts ) {
    if ( ( ‘gallery’ ) )
    $atts[‘size’] = ‘your-custom-size-name’;

    return $atts;
    add_filter( ‘shortcode_atts_gallery’, ‘yourfunctionname_gallery_atts’ );

  10. Thanks.

    Is there a way to find out the max depth of nested shortcode, what I mean is – let’s say I have [test][test][/test][/test], how can I try and get the max depth of the shortcodes ?


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s