Color Palette support setup with single array argument (backwards compatible)

[webmandesign]

Description

Allowing editor-color-palette theme support setup with a single array of colors parameter/argument. This way only one argument is passed to add_theme_support( 'editor-color-palette', $arg ) instead of multiple arguments for each color.

This code is backwards compatible with current implementation (colors are passed as multiple parameters/arguments).

Fixing issue #6425

(cc @chrisvanpatten and @jorgefilipecosta as per previous conversation)

[jorgefilipecosta]

Hi @webmandesign thank you for addressing backward compatibility 👍
@Luehrsen and @felixarntz, given your last useful insights on the color mechanisms would it be possible to share your thoughts on this PR?

[Luehrsen]

Is inlining a console.warn the way how we notice about depreciations? I think using _doing_it_wrong() is a safer approach.

This is probably from line 1171, but I would love to hear what @gziolo thinks about that.

[webmandesign]

The backcompat was actually suggested by @jorgefilipecosta so I've left it unchanged.

Should I remove the wp_add_inline_script part and introduce the _doing_it_wrong() for both instances of console.warn?

[jorgefilipecosta]

At the time of my suggestion _doing_it_wrong was not yet available.
I think we can now use the following:
_doing_it_wrong(
'add_theme_support()',
__( 'Setting colors using multiple parameters is deprecated. Please pass a single parameter with an array of colors. See https://wordpress.org/gutenberg/handbook/extensibility/theme-support/ for details.', 'gutenberg' ),
'3.2.0'
);

[webmandesign]

@Luehrsen and @jorgefilipecosta I've went ahead and applied the _doing_it_wrong on both console.warn instances.

[Luehrsen]

Do I guess the usage right, that you want to create the array somewhat programatically and just pass a variable to add_theme_support?

All in all I think it is a good method of doing things.

[chrisvanpatten]

@Luehrsen I won't speak for @webmandesign but that's what we'd like to do. Also makes it a little easier to re-use the color values in other contexts, e.g. auto-generating inline CSS for the classes, etc.

(something like…

$colors = [ /* imagine I'm an array */ ];

add_theme_support( 'editor-color-palette', $colors );

foreach ( $colors as $color ) {
 $css .= ".{$color['name']} { color: {$color['color']} }\n"
}

// echo out $css somewhere

[Luehrsen]

Although I like the approach, I would probably have done that with get_theme_support(). I think that would add consistency throughout the themes and coding standards, as I would just have to search for 'editor-color-palette' to see all code that handles the theme colors.

foreach( get_theme_support( 'editor-color-palette' ) as $color ) {
     $css .= ".{$color['name'} { color: {$color['color']} }\n"
}

[chrisvanpatten]

@Luehrsen That works as well! My code was just an example — but having a consistent input and output format makes sense I think, either way.

[webmandesign]

@Luehrsen Yes, that's correct, I want to create the array programatically and then just pass it into add_theme_support. I think that's the best approach (right now I can't think of any other add_theme_support feature being passed with multiple arguments nowadays, actually).

[webmandesign]

@jorgefilipecosta Backwards compatibility props goes to you :)

[Luehrsen]

I think this change makes sense. Passing the colors as a single array makes handling the theme support easier.

[jorgefilipecosta]

This PR seems to work fine in my tests 👍 . It looks like there is some consensus that this approach is better than what we had. Thank you @webmandesign for the effort in bringing this changes. I added a new commit updating the deprecation version.

[felixarntz]

I'm in favor of this change, as it does make things easier for theme developers.

It does make it a bit complex for Gutenberg itself (i.e. this PR), I really liked from the original approach that you could simply call get_theme_support( 'editor-color-palette' ) and have the final result to use, without needing to do some $theme_support = $theme_support[0]. But we wanna make things easy for theme developers, not ourselves, so +1.

[felixarntz]

+1 for changing this to using _doing_it_wrong() instead of printing a JS warning. After all it's something done wrong in PHP. :)

[felixarntz]

This is a solid implementation of BC, just a minor detail I think we should improve: I don't like calling get_theme_support() twice. I think we should make the original call to set $color_palette be only the (array) get_theme_support( 'editor-color-palette' ) part.

Then the if clause could check ! empty( $color_palette ) && isset( $color_palette[0]['color'] ), and if so, trigger the notice. Then an else clause could get the first array element to account for the new way.

One thing I'm not sure about, why is there an is_string() check. I might miss something, was it possible to provide strings only at some point?

[webmandesign]

@felixarntz
From my tests, we can not use (array) get_theme_support( 'editor-color-palette' ) width ! empty( $color_palette ) check as if the theme does not claim the support, this would be returned (which is not en empty array):

array(1) {
	[0] => bool(false)
}

The is_string() check is there to accommodate the old way of setting colors as add_theme_support( 'editor-color-palette', '#fff', '#000', ... );. Then this was updated to setting colors with multiple array arguments.

This code should do the trick though:

	$color_palette           = (array) get_theme_support( 'editor-color-palette' );

	// Backcompat for Color Palette set as multiple parameters.
	if ( is_string( $color_palette[0] ) || isset( $color_palette[0]['color'] ) ) {
		_doing_it_wrong(
			'add_theme_support()',
			__( 'Setting colors using multiple parameters is deprecated. Please pass a single parameter with an array of colors. See https://wordpress.org/gutenberg/handbook/extensibility/theme-support/ for details.', 'gutenberg' ),
			'3.4.0'
		);
	} else {
		$color_palette = current( $color_palette );
	}

[webmandesign]

@felixarntz I've went ahead and created #7695 addressing your concerns. Thanks for pointing this out!