Block Filters

Block Filters

Each block provided by this BU-Blocks has (at least) three filters that can be used to modify the block.

JavaScript Filters

Block Classnames

The filters for modifying the classname on the outermost element of the block follow the buBlocks.blockName.classNames naming convention. The argument passed to the callback is a string of the current class list.

Use of this filter would look like the following:

/**
 * Add a class to the Aside block.
 * 
 * @param {string} classes Classnames currently applied to the block.
 */
function asideBlockClassName( classes ) {
	return `${classes} my-added-class`;
}

wp.hooks.addFilter(
	'buBlocks.aside.classNames',
	'my-plugin-or-theme/blockFiltering',
	function asideBlockClassName
);

It's important to note that the classnames passed to this filter differ based on context. The edit function of the block passes the className property to the function that builds the class list for a block. The property contains the default Gutenberg-generated block class (and the publication class if BU-Prepress is active). The property is not available to the save function, however, so in that context, the className attribute is passed to the class list building function. (Gutenberg automatically applies the default class to the outermost element of the block in the save function.) The attribute only contains classes added to the block either by the alignment options, style options, or the Advanced > Additional CSS Class field. (This is why you'll see blocks without server-side rendering apply the classNames variable conditionally in the class list building function - it may not have any value when passed from the save function.) In other words, if there is a need to filter the default or publication classname of a block, the blocks.getBlockDefaultClassName filter provided by Gutenberg will need to be implemented.

After Opening

The filters for adding markup or components just after the opening tag of the block's outermost element in the edit function and the save function respectively follow the buBlocks.blockName.afterOpening and buBlocks.blockName.afterOpeningOutput naming conventions. These are separate filters as the value returned by their callback functions may need to be different depending on the use case. For simple cases, the filters can both hook the same function.

Also note that the only argument passed by these filters is an empty string, which may need to be modified if the intended use is to add a component to the block.

A simple example of the use of this filter:

/**
 * Add an h3 tag after the opening of the Aside block.
 */
function asideBlockAfterOpening() {
	return wp.element.createElement( 'h3', {}, 'My h3 content' );
}

wp.hooks.addFilter(
	'buBlocks.aside.afterOpening',
	'my-plugin-or-theme/blockFiltering',
	asideBlockAfterOpening
);
wp.hooks.addFilter(
	'buBlocks.aside.afterOpeningOutput',
	'my-plugin-or-theme/blockFiltering',
	asideBlockAfterOpening
);

Before Closing

The filter for adding markup or components just before the closing tag of the block's outermost element in the edit function and the save function respectively follow the buBlocks.blockName.beforeClosing and buBlocks.blockName.beforeClosingOutput naming conventions. Implementation of these filters is the same as the afterOpening and beforeClosing filters.

PHP Filters

Blocks with server-side rendering also have PHP filters to match their JavaScript equivalents. They follow these naming conventions:

• bu_blocks_blockname_classnames
• bu_blocks_blockname_after_opening
• bu_blocks_blockname_before_closing

In these cases, too, the classnames filter passes the string of default classes (in most cases), and the other two are currently set up with just an empty string.

Additional Filtering

For more extensive changes, like removing, adding, or even potentially reordering fields, additional filters would need to be added to the block. For example, refer to the use of the buPrepress.editionBlocks.decorativeTitleField and buPrepress.editionBlocks.decorativeTitleOutput filters in the Edition: Contact Us block from BU-Prepress and how they are leveraged by the r-editorial theme. Also refer to the Edition: Featured Classnote block's PHP file (and the accompanying hook in r-editorial) for an example of how to leverage these filters in blocks with server-side rendering.

List of Block Filters

Aside

• buBlocks.aside.classNames
• buBlocks.aside.afterOpening
• buBlocks.aside.beforeClosing
• buBlocks.aside.afterOpeningOutput
• buBlocks.aside.beforeClosingOutput

BUniverse

• buBlocks.buniverse.classNames
• buBlocks.buniverse.afterOpening
• buBlocks.buniverse.beforeClosing
• buBlocks.buniverse.afterOpeningOutput
• buBlocks.buniverse.beforeClosingOutput

Button

• buBlocks.button.classNames
• buBlocks.button.afterOpening
• buBlocks.button.beforeClosing
• buBlocks.button.afterOpeningOutput
• buBlocks.button.beforeClosingOutput

Click to Tweet

This is a format added to the Paragraph block, and as such, does not have any filters.

Custom HTML

The nature of this block is such that it neither needs nor lends itself to the addition of filters.

Drawer

• buBlocks.drawer.classNames
• buBlocks.drawer.afterOpening
• buBlocks.drawer.beforeClosing
• buBlocks.drawer.afterOpeningOutput
• buBlocks.drawer.beforeClosingOutput

Headline

• buBlocks.headline.classNames

The headline block consists of a single RichText component, and therefore has no beforeOpening or afterClosing filters.

Intro Paragraph

• buBlocks.introParagraph.classNames
• buBlocks.introParagraph.afterOpening
• buBlocks.introParagraph.beforeClosing
• buBlocks.introParagraph.afterOpeningOutput
• buBlocks.introParagraph.beforeClosingOutput

Leadin

• buBlocks.leadin.classNames
• buBlocks.leadin.afterOpening
• buBlocks.leadin.beforeClosing
• buPrepress.PrimaryTerm
  • General hook used BU-Prepress for outputting the primary term markup. Accepts:
    • content {string} Original content to filter (unused).
    • props {object} The block properties.
    • classes {string} Additional classes to add to the primary term markup.
• buBlocks.leadin.metaBar
  • Used by BU-Prepress for outputting the metabar block. Accepts:
    • content {string} Original content to filter (unused).
    • metabar {boolean} Whether to display the metabar.
• bu_blocks_leadin_classnames
• bu_blocks_leadin_after_opening
• bu_blocks_leadin_before_closing
• bu_blocks_leadin_primary_term
  • Action hook used by BU-Prepress for displaying the primary term markup. Accepts:
    • int $post_id The ID of the post containing the block.
• bu_blocks_leadin_meta_bar
  • Action hook used by BU-Prepress for displaying the metabar block. Accepts:
    • bool $display Whether to display the metabar.
• bu_blocks_publication_slug
  • General hook used by BU-Prepress for filtering the publication slug: Accepts:
    • string $publication_slug The publication slug. 'bu-blocks' by default.
• bu_blocks_background
  • General action hook used by the Background component. Accepts:
    • array $attributes The block attributes.
    • mixed $image_size Image size to display.

Listicle

• buBlocks.listicle.classNames
• buBlocks.listicle.afterOpening
• buBlocks.listicle.beforeClosing
• buBlocks.listicle.afterOpeningOutput
• buBlocks.listicle.beforeClosingOutput

Modal

• buBlocks.modal.classNames
• buBlocks.modal.afterOpening
• buBlocks.modal.beforeClosing
• buBlocks.modal.afterOpeningOutput
• buBlocks.modal.beforeClosingOutput

Photo Essay

• buBlocks.photoEssay.classNames
• buBlocks.photoEssay.afterOpening
• buBlocks.photoEssay.beforeClosing
• buBlocks.photoEssay.afterOpeningOutput
• buBlocks.photoEssay.beforeClosingOutput

Pull Quote

• buBlocks.pullquote.classNames
• buBlocks.pullquote.afterOpening
• buBlocks.pullquote.beforeClosing
• buBlocks.pullquote.afterOpeningOutput
• buBlocks.pullquote.beforeClosingOutput

Related Stories

• buBlocks.relatedStories.classNames
• buBlocks.relatedStories.afterOpening
• buBlocks.relatedStories.beforeClosing
• buBlocks.relatedStories.yarppPostTypes
  • Used by Prepress to filter the post type YARPP should retrieve. Accepts:
    • postTypes {array} The array of post types. Default [ 'post' ].
• buBlocks.relatedStories.postTypes
  • Used by Prepress to filter the post type retrieved by manual searches. Accepts:
    • postTypes {array} The array of post types. Default [ 'post' ].
• buBlocks.relatedStories.displayListItem
  • Used by Prepress to append the Shared From markup. Accepts:
    • content {string} Original content to filter (unused).
    • post {object} The post being displayed in the block.
    • currentPost {string} The post containing the block.
• bu_blocks_related_stories_class_names
• bu_blocks_related_stories_after_opening
• bu_blocks_related_stories_before_closing
• bu_prepress_related_stories_block_attributes
  • Filters the attributes used when rendering the related stories block. Unused. Accepts:
    • array $attributes Attributes provided for block rendering.
• bu_blocks_related_stories_post_types
  • Used by BU-Prepress to filter the post types used when displaying related stories. Accepts:
    • array $post_types A list of post types to pass.
    • bool $manual Whether the request is manual (true) or YARPP (false).
• bu_blocks_related_stories_article_category
  • Filters the display of the post category. Accepts:
    • bool $display Whether to display the post category. Default false.
    • object $post The post being displayed in the block.
• bu_blocks_related_stories_close_article
  • Used by BU-Prepress to display the Shared From markup. Accepts:
    • object $post The post being displayed in the block.
    • int $article_id The ID of the post containing the block.

Slideshow

Stats

• buBlocks.stats.classNames
• buBlocks.stats.afterOpening
• buBlocks.stats.beforeClosing
• buBlocks.stats.afterOpeningOutput
• buBlocks.stats.beforeClosingOutput