WordPress.org

Make WordPress Core

Opened 6 months ago

Closed 2 months ago

#53792 closed defect (bug) (fixed)

About Docblock in wp_style_add_data

Reported by: tmatsuur Owned by: desrosj
Milestone: 5.9 Priority: normal
Severity: normal Version: 5.8
Component: Script Loader Keywords: has-patch commit
Focuses: docs Cc:

Description

In version 5.8, I think 'path' can be specified in the parameter $key, but there is no mention of this in Docblock.

I think it is also important to add that if the pathname specified in $value is an absolute path, it will be output inline.

Attachments (1)

53792.diff (1.2 KB) - added by desrosj 2 months ago.

Download all attachments as: .zip

Change History (8)

#1 @SergeyBiryukov
6 months ago

  • Component changed from General to Script Loader
  • Keywords needs-patch added
  • Milestone changed from Awaiting Review to 5.9

#2 @hilayt24
4 months ago

  • Keywords needs-screenshots added

Hi @tmatsuur thank you for the ticket. Can you please provide some more details.

#3 @tmatsuur
4 months ago

Thanks @hilayt24

In the docblock of the wp_maybe_inline_styles function, which was added in version 5.8, there is a statement like this

 * This improves performance and sustainability, and is opt-in. Stylesheets can opt in
 * by adding `path` data using `wp_style_add_data`, and defining the file's absolute path:
 *
 *     wp_style_add_data( $style_handle, 'path', $file_path );

In the docblock of the wp_style_add_data function in version 5.8.1, there is no description of "path" for the second parameter.

/**
 * Add metadata to a CSS stylesheet.
 *
 * Works only if the stylesheet has already been added.
 *
 * Possible values for $key and $value:
 * 'conditional' string      Comments for IE 6, lte IE 7 etc.
 * 'rtl'         bool|string To declare an RTL stylesheet.
 * 'suffix'      string      Optional suffix, used in combination with RTL.
 * 'alt'         bool        For rel="alternate stylesheet".
 * 'title'       string      For preferred/alternate stylesheets.
 *
 * @see WP_Dependencies::add_data()
 *
 * @since 3.6.0
 *
 * @param string $handle Name of the stylesheet.
 * @param string $key    Name of data point for which we're storing a value.
 *                       Accepts 'conditional', 'rtl' and 'suffix', 'alt' and 'title'.
 * @param mixed  $value  String containing the CSS data to be added.
 * @return bool True on success, false on failure.
 */

An example of the use of "path" as the second parameter of the wp_style_add_data function is the register_block_style_handle function added in version 5.5.

Lines 169 - 171 of wp-includes/blocks.php

	if ( $has_style_file ) {
		wp_style_add_data( $style_handle, 'path', $style_file );
	}

This made me think that the docblock of the wp_style_add_data function needs to be modified.

#4 @SergeyBiryukov
4 months ago

  • Keywords needs-screenshots removed

This ticket was mentioned in Slack in #core by audrasjb. View the logs.


2 months ago

@desrosj
2 months ago

#6 @desrosj
2 months ago

  • Keywords has-patch commit added; needs-patch removed

Thanks @tmatsuur for the additional details! Indeed this should be noted in the docblock. 53792.diff adds this.

#7 @desrosj
2 months ago

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

In 52216:

Script Loader: Document path as an accepted value for $key in wp_style_add_data().

Follow up to [50836].

Props tmatsuur.
Fixes #53792.

Note: See TracTickets for help on using tickets.