Intelligently insert speed bumps into site content.
What are the default rules?
The default options for speed bumps are currently:
- Never insert in a post fewer than 8 paragraphs long, or fewer than 1200 characters.
- Never insert before the the third paragraph, or before 75 words into the post.
- Never insert fewer than 3 paragraphs or 75 words from the end of the article.
- At least one paragraph from an iframe or embed.
- At least two paragraphs from an image.
- At least one paragraph from any other speed bump in the post.
How to add more specific rules?
Adding a custom rule for a speed bump is a matter of defining a function and hooking it to the speed_bumps_{id}_constraints filter. The function hooked to that filter will receive several arguments to determine the state of the content, surrounding paragraphs, and other context, and can return false to block insertion.
Simple, stupid example: You have a speed bump called “rickroll” which inserts a beautiful musical video throughout your content. You really need this viral bump (publisher’s words, not yours) so you disable minimum content length and the rules regarding acceptable speed bump distance from start/end of the post. Greedy!
register_speed_bump( 'rickroll', array(
'string_to_inject' => function() { return ''; },
'minimum_content_length' => false,
'from_start' => false,
'from_end' => false,
));
add_filter( 'the_content', 'insert_speed_bumps', 1 );
But, maybe that’s a little too extreme. You want to show it in certain situations, say, only when the previous paragraph contains the phrase ‘give {something} up’. Here’s how you would achieve that:
add_filter( 'speed_bumps_rickroll_constraints', 'give_you_up', 10, 4 );
function give_you_up( $can_insert, $context, $args, $already_inserted ) {
if ( ! preg_match( '/give [^ ]+ up/i', $context['prev_paragraph'] ) ) {
$can_insert = false;
}
return $can_insert;
}
You could also disable it altogether with this filter (although why you would disable so soon after addition, only Rick Astley himself could answer):
add_filter( 'speed_bumps_rickroll_constraints', '__return_false' );
How to remove default rules?
Each rule is hooked to that speed bump’s “constraints” filter. To remove a rule, simply remove the filter which defines that rule, like these lines which remove the default rules for your speed bump:
remove_filter( 'speed_bumps_{id}_constraints', '\Speed_Bumps\Constraints\Text\Minimum_Text::content_is_long_enough_to_insert' );
remove_filter( 'speed_bumps_{id}_constraints', '\Speed_Bumps\Constraints\Text\Minimum_Text::meets_minimum_distance_from_start' );
remove_filter( 'speed_bumps_{id}_constraints', '\Speed_Bumps\Constraints\Text\Minimum_Text::meets_minimum_distance_from_end' );
remove_filter( 'speed_bumps_{id}_constraints', '\Speed_Bumps\Constraints\Content\Injection::less_than_maximum_number_of_inserts' );
remove_filter( 'speed_bumps_{id}_constraints', '\Speed_Bumps\Constraints\Content\Injection::meets_minimum_distance_from_other_inserts' );
remove_filter( 'speed_bumps_{id}_constraints', '\Speed_Bumps\Constraints\Elements\Element_Constraints::meets_minimum_distance_from_elements' );
