[wp-trac] [WordPress Trac] #15155: Allow filtering of shortcode attributes

[WordPress Trac]

#15155: Allow filtering of shortcode attributes
---------------------------------+------------------
 Reporter:  coffee2code          |       Owner:
     Type:  enhancement          |      Status:  new
 Priority:  normal               |   Milestone:  3.6
Component:  Shortcodes           |     Version:  2.5
 Severity:  normal               |  Resolution:
 Keywords:  has-patch 3.5-early  |
---------------------------------+------------------
Description changed by DrewAPicture:

Old description:

> It would be handy to have the ability to filter the array returned from
> `shortcode_atts()`.  This would allow plugins to take the default
> shortcode attributes, the user supplied attributes, and the merged array
> of those two into account prior to `shortcode_atts()` returning.
>
> Potential uses:
>  * Override the default shortcode attributes (in a fashion)
>  * Ignore certain attribute values from the user and instead use the
> defaults
>  * Dynamically generate shortcode attribute values
>  * Modifying the behavior of a shortcode handler via attributes without
> redefining and rewriting the handler, particularly if the shortcode
> handler doesn't present filters of its own
>
> This would be particularly useful to modify the behavior of core-supplied
> shortcodes.  For instance, #14390 requests a way of omitting post
> thumbnails from the gallery shortcode.  Using this patch, this could
> easily be done via hooks in a number of ways (i.e. omit post thumbnails
> if the 'exclude' attribute isn't supplied, or always ignore post
> thumbnails, etc).  In fact, these hooks allow for custom exclusion of any
> number of images for any number of custom reasons.
>
> The patch introduces two filters, "shortcode_atts_$shortcode" and
> "shortcode_atts".  The former allows hooking only the shortcode_atts for
> a specified shortcode, whereas the latter is a more generic hook.
>
> `shortcode_atts()` really has no context, so I introduced an optional
> argument, `$shortcode`.  If supplied, the new hooks are fired.  I opted
> not to fire them if no `$shortcode` was supplied since the lack of
> context (namely, the name of the shortcode whose attributes are being
> processed) makes the use of the hooks a questionable proposition.  The
> patch amends all existing `shortcode_atts()` calls to include the new
> argument.  We'd want to promote use of the argument going forward, which
> is why I (perhaps overzealously) made use of  `_deprecated_argument()` to
> alert developers not to a deprecated argument, but to an added argument
> (is there a better way? making the argument required would of course
> break a lot plugins).
>
> By way of example, here's a patch for #14390 making use of this patch to
> omit the post thumbnail from the gallery shortcode:
>
> {{{
> add_filter( 'shortcode_atts_gallery',
> 'gallery_shortcode_exclude_thumbnail', 10, 3 );
>
> /**
>  * Exclude post thumbnail image from gallery if user doesn't explicitly
> exclude any images
>  *
>  * @since 3.1
>  * @param array $result The shortcode_atts() merging of $defaults and
> $atts
>  * @param array $defaults The default attributes defined for the
> shortcode
>  * @param array $atts The attributes supplied by the user within the
> shortcode
>  * @return array The potentially modified $result array
>  *
>  */
> function gallery_shortcode_exclude_thumbnail( $result, $defaults, $atts )
> {
>         if ( empty( $atts['exclude'] ) )
>                 $result['exclude'] = get_post_thumbnail_id();
>         return $result;
> }
> }}}
>
> Another example would be modifying the `[caption]` shortcode to prepend
> or append text to whatever caption the user provided.
>
> {{{
> function append_copyright_to_caption( $result, $defaults, $atts ) {
>         $copyright = '© 2010 Example, Inc.';
>         if ( isset( $result['caption'] )  && ! empty( $result['caption']
> ) )
>                 $result['caption'] .= "<br />$copyright";
>         else
>                 $result['caption'] =  $copyright;
>         return $result;
> }
> add_filter( 'shortcode_atts-caption', 'append_copyright_to_caption', 10,
> 3);
> }}}

New description:

 It would be handy to have the ability to filter the array returned from
 `shortcode_atts()`.  This would allow plugins to take the default
 shortcode attributes, the user supplied attributes, and the merged array
 of those two into account prior to `shortcode_atts()` returning.

 Potential uses:
  * Override the default shortcode attributes (in a fashion)
  * Ignore certain attribute values from the user and instead use the
 defaults
  * Dynamically generate shortcode attribute values
  * Modifying the behavior of a shortcode handler via attributes without
 redefining and rewriting the handler, particularly if the shortcode
 handler doesn't present filters of its own

 This would be particularly useful to modify the behavior of core-supplied
 shortcodes.  For instance, #14390 requests a way of omitting post
 thumbnails from the gallery shortcode.  Using this patch, this could
 easily be done via hooks in a number of ways (i.e. omit post thumbnails if
 the 'exclude' attribute isn't supplied, or always ignore post thumbnails,
 etc).  In fact, these hooks allow for custom exclusion of any number of
 images for any number of custom reasons.

 The patch introduces two filters, "shortcode_atts_$shortcode" and
 "shortcode_atts".  The former allows hooking only the shortcode_atts for a
 specified shortcode, whereas the latter is a more generic hook.

 `shortcode_atts()` really has no context, so I introduced an optional
 argument, `$shortcode`.  If supplied, the new hooks are fired.  I opted
 not to fire them if no `$shortcode` was supplied since the lack of context
 (namely, the name of the shortcode whose attributes are being processed)
 makes the use of the hooks a questionable proposition.  The patch amends
 all existing `shortcode_atts()` calls to include the new argument.  We'd
 want to promote use of the argument going forward, which is why I (perhaps
 overzealously) made use of  `_deprecated_argument()` to alert developers
 not to a deprecated argument, but to an added argument (is there a better
 way? making the argument required would of course break a lot plugins).

 By way of example, here's a patch for #14390 making use of this patch to
 omit the post thumbnail from the gallery shortcode:

 {{{
 add_filter( 'shortcode_atts_gallery',
 'gallery_shortcode_exclude_thumbnail', 10, 3 );

 /**
  * Exclude post thumbnail image from gallery if user doesn't explicitly
 exclude any images
  *
  * @since 3.1
  * @param array $result The shortcode_atts() merging of $defaults and
 $atts
  * @param array $defaults The default attributes defined for the shortcode
  * @param array $atts The attributes supplied by the user within the
 shortcode
  * @return array The potentially modified $result array
  *
  */
 function gallery_shortcode_exclude_thumbnail( $result, $defaults, $atts )
 {
         if ( empty( $atts['exclude'] ) )
                 $result['exclude'] = get_post_thumbnail_id();
         return $result;
 }
 }}}

 Another example would be modifying the `[caption]` shortcode to prepend or
 append text to whatever caption the user provided.

 {{{
 function append_copyright_to_caption( $result, $defaults, $atts ) {
         $copyright = '&copy; 2010 Example, Inc.';
         if ( isset( $result['caption'] )  && ! empty( $result['caption'] )
 )
                 $result['caption'] .= "<br />$copyright";
         else
                 $result['caption'] =  $copyright;
         return $result;
 }
 add_filter( 'shortcode_atts_caption', 'append_copyright_to_caption', 10,
 3);
 }}}

--

-- 
Ticket URL: <http://core.trac.wordpress.org/ticket/15155#comment:27>
WordPress Trac <http://core.trac.wordpress.org/>
WordPress blogging software