[wp-trac] [WordPress Trac] #59559: The Image block lightbox introduces an undocumented exception on how the render_block_{$this->name} filter is supposed to work

[WordPress Trac]

#59559: The Image block lightbox introduces an undocumented exception on how the
render_block_{$this->name} filter is supposed to work
--------------------------+--------------------
 Reporter:  afercia       |      Owner:  (none)
     Type:  defect (bug)  |     Status:  new
 Priority:  normal        |  Milestone:  6.4
Component:  Editor        |    Version:  trunk
 Severity:  normal        |   Keywords:
  Focuses:  docs          |
--------------------------+--------------------
 When an Image block is set to open the image in the lighbox, the actual
 lightbox markup is added to the block via the `render_block_{$this->name}`
 filter.

 The filter runs at priority 15. See in
 [https://github.com/WordPress/gutenberg/blob/15ece32d14d69f17f442dc7456c1781fd3bd5efa/packages
 /block-library/src/image/index.php#L73 the related code in the github
 repo]:

 I see two issues with this implementation:

 1
 The implementation actually introduces an exception on how the
 `render_block_{$this->name}` is supposed to work. Or, better, on the
 actual content the filter will receive.

 Using the filter like one would normally do with the default priority will
 only filter the original block content, regardless of whether lightbox is
 enabled or not:

 `add_filter( 'render_block_core/image', 'my_custom_html' )`

 As a developer, I would expect this filter to always receive the _actual_
 block content:
 - When lightbox ie disabled: I'd expect the normal Image block content.
 - When lightbox ie enabled: I'd expect the Image block content including
 the lightbox markup.

 Instead, to be able to get the lightbox markup, I'd need to change
 priority. This will return the actual markup including the lightbox one:

 `add_filter( 'render_block_core/image', 'my_custom_html', 15 )`

 As said, this is an undocumented exception at the very lest:
 - It should be clearly explained in
 [https://developer.wordpress.org/reference/hooks/render_block_this-name/
 the filter documentation].
 - It should be mentioned prominently in the 6.4 release notes.

 In any case, I'm not sure altering the expected behavior of a filter in
 this way is ideal.

 2
 The way the lightbox markup is added to the block markup is, in my
 opinion, inherently fragile.
 [https://github.com/WordPress/gutenberg/blob/15ece32d14d69f17f442dc7456c1781fd3bd5efa/packages
 /block-library/src/image/index.php#L303 The code assumes to find a figure
 element]. If for any reason plugins are replacing the figure element by
 using the filter with normal priority, the lightbox will simply not work.

 Marking this ticket for 6.4 consideration because at least the
 documentation part should be addressed soon.

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/59559>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform