WordPress.org

Make WordPress Core

Opened 3 years ago

Closed 14 months ago

Last modified 13 months ago

#15155 closed enhancement (fixed)

Allow filtering of shortcode attributes

Reported by: coffee2code Owned by: nacin
Milestone: 3.6 Priority: normal
Severity: normal Version: 2.5
Component: Shortcodes Keywords: has-patch 3.5-early commit needs-codex
Focuses: Cc:

Description (last modified by DrewAPicture)

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);

Attachments (6)

15155.diff (1.7 KB) - added by coffee2code 3 years ago.
Patch mentioned in ticket.
15155.2.diff (1.4 KB) - added by coffee2code 3 years ago.
Changes as suggested by @nacin (see associated comment for details)
ut.15155.diff (2.4 KB) - added by coffee2code 2 years ago.
WP unit tests for proposed patch.
15155.2-refresh.diff (1.4 KB) - added by DrewAPicture 14 months ago.
Refreshes 15155.2.diff
15155.3.diff (1.4 KB) - added by DrewAPicture 14 months ago.
shortcode_atts_{$shortcode}
ut.15155.2.diff (2.4 KB) - added by coffee2code 14 months ago.
Refresh of unit tests

Download all attachments as: .zip

Change History (45)

coffee2code3 years ago

Patch mentioned in ticket.

comment:1 Denis-de-Bernardy3 years ago

  • Cc Denis-de-Bernardy added

comment:2 nkuttler3 years ago

Yes, this looks like a good idea. Let's see if we can get this or something similar into 3.2 :-)

comment:3 nkuttler3 years ago

  • Cc wp@… added

comment:4 markjaquith3 years ago

  • Milestone changed from Awaiting Review to Future Release

This sounds really powerful.

comment:5 WraithKenny3 years ago

  • Cc Ken@… added

comment:6 lancewillett3 years ago

  • Cc lancewillett added

+1 for this. Have run into several cases lately where themes need to override the default gallery shortcode — and it's overkill to redo the entire gallery template just to change one parameter.

comment:7 F J Kaiser3 years ago

  • Cc 24-7@… added

+1 I was searching for a way to not rewrite the whole "walker" for the gallery shortcode and this solution is just ...wow(!): extremly powerful in lots of cases. @coffee2code - Thanks!

comment:8 djr3 years ago

<blockquote>My approach presumes that if the user is excluding at least one image, they will know enough to be able to exclude the post thumbnail as well. And if for some reason they'd like to include the post thumbnail image as part of the gallery, they can still do so.</blockquote>
Food for thought: not all images are explicitly excluded. Some, like post_thumbnail, are automatically attached, e.g. by plugins like Regenerate Thumbnails (not sure) or Auto Post Thumbnail (the one we're using). See this forum post for a scenario where this patch wouldn't help. I'd really love to see an explicit 'use_post_thumbnail' [Yes/No] filter for the gallery shortcode.

Version 2, edited 3 years ago by djr (previous) (next) (diff)

comment:9 djr3 years ago

  • Cc jeanpaul@… added

comment:10 djr3 years ago

Added to this: the default order for most galleries is menu_order if I recall correctly? The problem I'm seeing is that *automatically* added post_thumbnails (with wp_insert_attachment() and wp_generate_attachment_metadata() ) aren't assigned an (ordinal) menu order ID in the Media Uploader Gallery tab, which is what the gallery shortcode expects for sorting by menu order. The added patch doesn't seem to consider sorting by (gallery) menu order, or at least not in my install.

Last edited 3 years ago by djr (previous) (diff)

comment:11 chipbennett3 years ago

  • Cc chip@… added

coffee2code3 years ago

Changes as suggested by @nacin (see associated comment for details)

comment:12 coffee2code3 years ago

As per consultation with @nacin, original patch has been modified and attached as 15155.2.diff:

  • Removed throwing warning (via either _deprecated_argument() or _doing_it_wrong()) if the optional $shortcode argument is not supplied
  • Removed generic shortcode_atts filter
  • Changed proposed filter name from shortcode_atts-$shortcode to shortcode_atts_$shortcode (dash to underscore)

Without throwing warnings to developers, though, I wonder how well (widely and quickly) the new argument will propagate... (though I acknowledge both _deprecated_argument() or _doing_it_wrong() are not appropriate to denote a newly added recommended argument). It would then become a matter of shortcode developers actively allowing their shortcode to be modified (by optionally specifying the argument) versus trying to make it so ANY shortcode's attributes could be modified (if we progressed to requiring, or strongly recommending, the argument).

comment:13 coffee2code3 years ago

Closed #18472 as a duplicate (it requested attribute handling that was specific to the gallery shortcode, which is more generically handled here).

comment:14 kovshenin3 years ago

  • Cc kovshenin@… added

comment:15 doug3 years ago

  • Cc wordpress@… added

comment:16 adambackstrom3 years ago

  • Cc adambackstrom added

comment:17 carstenbach2 years ago

  • Cc carstenbach added

coffee2code2 years ago

WP unit tests for proposed patch.

comment:18 coffee2code2 years ago

Patch 15155.2.diff still applies cleanly as of r20564.

Also attached WP unit test patch ut.15155.diff (patched against [UT694]) with tests that pass when the WP patch is applied.

comment:19 nacin23 months ago

  • Keywords 3.5-early added
  • Version changed from 3.0.1 to 2.5

Fine with this.

comment:20 dougal23 months ago

  • Cc dougal@… added

Please add this for 3.5. I was just wrestling with this very problem for a plugin. My use case is wanting to override the gallery shortcode defaults, because my plugin wants the 'link' att to default to 'file'.

comment:21 navjotjsingh18 months ago

  • Cc navjotjsingh@… added

comment:22 lancewillett14 months ago

Is this going to make it into 3.6?

comment:23 markoheijnen14 months ago

I think we should.

comment:24 SergeyBiryukov14 months ago

  • Milestone changed from Future Release to 3.6

comment:25 follow-up: markjaquith14 months ago

Yes please! Solid idea. Can someone verify that it still applies and tests cleanly? If it does, let's land it.

comment:26 DrewAPicture14 months ago

#23298 is (sorta) related.

DrewAPicture14 months ago

Refreshes 15155.2.diff

comment:27 DrewAPicture14 months ago

  • Description modified (diff)

comment:28 in reply to: ↑ 25 DrewAPicture14 months ago

Replying to markjaquith:

Yes please! Solid idea. Can someone verify that it still applies and tests cleanly? If it does, let's land it.

15155.2-refresh.diff applies cleanly and the copyright-appended-to-caption example works for me. Not sure about the tests.

DrewAPicture14 months ago

shortcode_atts_{$shortcode}

comment:29 DrewAPicture14 months ago

  • Cc xoodrew@… added

Kind of a nit for consistency, but 15155.3.diff changes the concat style in the filter from:

'shortcode_atts_' . $shortcode

to

"shortcode_atts_{$shortcode}"

coffee2code14 months ago

Refresh of unit tests

comment:30 doug14 months ago

  • Cc wordpress@… removed

comment:31 coffee2code14 months ago

Refreshed (ut.15155.2.diff) (along with minor doc/naming/spacing tweaks) the original unit tests so they apply cleanly against the since-revamped unit test code. Tests pass with any of the latest patches applied.

comment:32 djr14 months ago

  • Cc jeanpaul@… removed

comment:33 betzster14 months ago

  • Cc j@… added

comment:34 goto1014 months ago

  • Cc dromsey@… added

comment:35 SergeyBiryukov14 months ago

  • Keywords commit added

comment:36 nacin14 months ago

  • Owner set to nacin
  • Resolution set to fixed
  • Status changed from new to closed

In 23626:

Add shortcode_atts_$shortcode filter for when the name of the shortcode is passed to shortcode_atts(). props coffee2code. fixes #15155.

comment:37 nacin14 months ago

In 1239/tests:

Add shortcode_atts() filter tests. see #15155. props coffee2code.

comment:38 DrewAPicture14 months ago

  • Keywords 3.6-codex added

comment:39 DrewAPicture13 months ago

  • Keywords needs-codex added; 3.6-codex removed
Note: See TracTickets for help on using tickets.