Gutenberg experiments settings page. #16626

tellthemachines · 2019-07-17T07:28:15Z

Description

Addresses #16318 .

Added sub-menu page to the Gutenberg admin menu section;
Created two settings checkbox fields (Widgets screen and Legacy widget block).

The settings are not actually doing anything yet. As per this comment we still need to discuss what the best strategy is for leaving options enabled or disabled by default.

I'm also not hugely comfortable with the WP Settings API (or with PHP dev in general) so please bear with me here 😄 as I have a few questions:

What should be added in the @since in function docs when we're not sure what version this is being shipped with?
Do checkbox values need any extra validation when being read from/written to the database?
This is a new settings page, so semantically it should have an h1 tag. However, add_settings_section generates an h2 and populates it with the section title by default. Is there any way of disabling this? Or, failing that, of adding settings fields without adding a section?
Similar problem to the above with add_settings_field: it outputs the field name inside a th, which repeats the field label. Is there any workaround for this?

How has this been tested?

Only checked this locally while building.

Screenshots

Types of changes

New feature (non-breaking change which adds functionality)

Checklist:

My code is tested.
My code follows the WordPress code style.
My code follows the accessibility standards.
My code has proper inline documentation.
I've included developer documentation if appropriate.

lib/experiments-page.php

Soean

Some strings are not ready for translation.

lib/experiments-page.php

talldan · 2019-07-17T07:54:58Z

lib/experiments-page.php

+	$value   = isset( $options[ $args[1] ] ) ? 1 : 0;
+	?>
+		<input type="checkbox" name="<?php echo 'gutenberg-experiments[' . $args[1] . ']'; ?>" id="<?php echo $args[1]; ?>" value="1" <?php checked( 1, $value ); ?> />
+		<label for="<?php echo $args[1]; ?>">


It'd be nice to assign these ($args[0], $args[1]) to variables with informative names at the top of the function. I notice now it's in the comment above the function, but I still think it'd be a nice improvement 😄 .

I've also added this comment below with a more "in depth" explanation :)

Good shout 👍

draganescu · 2019-07-17T07:55:44Z

lib/experiments-page.php

+ *
+ * @param array $args ( $label, $id ).
+ */
+function display_experiment_field( $args ) {


The $args parameter for the add_settings_field function is passed exactly as defined with call_user_func into the callback therefore it would be nice if $args would be a keyed array such as:

add_settings_field( 'gutenberg-widgets-screen', 'Widgets Screen', 'display_experiment_field', 'gutenberg-experiments', 'gutenberg_experiments_section', array( 'label' => 'Widgets Screen', 'id' => 'gutenberg-widgets-screen', ) );

because then the code would be easier to read, like:

<label for="<?php echo $args['id']; ?>"> <?php echo $args['label']; ?> </label>

Or you could use list to extract named variables out of the args array, for the same readability goal:

function display_experiment_field( $args ) { list($label, $id) = $args;

but this approach is breakable if the order in the settings definition will change, so I would go for the named keys option.

Oooh good tip, thanks Andrei!

noisysocks · 2019-07-18T05:20:27Z

Nice work on this! 🎉

What should be added in the @SInCE in function docs when we're not sure what version this is being shipped with?

This should correspond to the Gutenberg plugin version. The next version will be 6.2.

Do checkbox values need any extra validation when being read from/written to the database?

Nope, the Settings API handles validation and writing to the database 🙂

This is a new settings page, so semantically it should have an h1 tag. However, add_settings_section generates an h2 and populates it with the section title by default. Is there any way of disabling this? Or, failing that, of adding settings fields without adding a section?

You can pass an empty string ('') to $title in add_settings_section(), though, strangely, this is not documented!

Similar problem to the above with add_settings_field: it outputs the field name inside a th, which repeats the field label. Is there any workaround for this?

It doesn't look like this is possible.

Instead of fighting the API, could we make this screen look more like the other settings pages where groups of checkboxes are grouped together? (cc. @karmatosed)

Another option is to make the label on the right begin with a verb.

Both those screenshots are from the Settings > Discussion page in WP Admin.

The settings are not actually doing anything yet. As per this comment we still need to discuss what the best strategy is for leaving options enabled or disabled by default.

I think having them OFF by default makes the most sense. That way, if something that's experimental breaks, the user can take a guess at why (because they explicitly enabled an experiment).

To implement the widgets screen setting, we could wrap our call to add_submenu_page() in an if ( ) that checks that the setting is on.

gutenberg/gutenberg.php

Lines 46 to 53 in e82b7c6

    
           add_submenu_page( 
        
           	'gutenberg', 
        
           	__( 'Widgets (beta)', 'gutenberg' ), 
        
           	__( 'Widgets (beta)', 'gutenberg' ), 
        
           	'edit_theme_options', 
        
           	'gutenberg-widgets', 
        
           	'the_gutenberg_widgets' 
        
           );

I'm less certain on how to implement the legacy widget block setting. We might be able to use the allowed_block_types hook, but this only lets us specify a whitelist and not a blacklist. Do you have any ideas, @jorgefilipecosta?

swissspidy · 2019-07-18T09:06:03Z

lib/experiments-page.php

+		'gutenberg-experiments',
+		'gutenberg_experiments_section',
+		array(
+			'label' => __( 'Legacy Widget Block', 'gutenberg' ),


That's not really accessible I think. It should be more like "Enable legacy widget block"

swissspidy · 2019-07-18T09:06:14Z

lib/experiments-page.php

+		'gutenberg-experiments',
+		'gutenberg_experiments_section',
+		array(
+			'label' => __( 'Widgets Screen', 'gutenberg' ),


That's not really accessible I think. It should be more like "Enable new widgets screen"

Good point! Have changed the labels.

tellthemachines · 2019-07-19T01:02:45Z

Thanks for answering all my questions @noisysocks !

It doesn't look like this is possible.

And thanks for pointing me at the code. I found that by passing a label_for argument to the callback passed to add_settings_field we can get it to output the actual label inside that th 😀
This is also not documented. Where is the best place to open a ticket to add this into the docs? It's a really useful thing to know about.

kjellr · 2019-07-19T15:40:06Z

We discussed this today in the #accessibility weekly slack chat, and agreed that we should rework the labels here a little bit.

We should use "Widgets" as a single group for the two fields, and add more specific labels to the right of each checkbox. Here's a quick mockup:

mapk · 2019-07-19T16:01:20Z

We should use "Widgets" as a single group for the two fields, and add more specific labels to the right of each checkbox.

This feels more consistent with other "Settings" pages and provides clarity. Let's go with that mockup.

afercia · 2019-07-19T16:23:35Z

Example of the markup used for the existing "Email me whenever" group under Settings > Discussion (generated with the existing Settings API):

<tr>
    <th scope="row">Email me whenever</th>
    <td>
        <fieldset>
            <legend class="screen-reader-text">Email me whenever</legend>
            <label for="comments_notify">
                <input name="comments_notify" type="checkbox" id="comments_notify" value="1" checked="checked">
                 Anyone posts a comment
             </label><br>

            <label for="moderation_notify">
                <input name="moderation_notify" type="checkbox" id="moderation_notify" value="1" checked="checked">
                A comment is held for moderation
            </label>
        </fieldset>
    </td>
</tr>

youknowriad

Thanks for the PR. Great page.

Some remarks:

I feel widgets screen and legacy widget block work together, so it should be just one option for both
We should have an option to show the hidden menu block

I also wonder if we should make the settings work before merging. I think the "editor settings" could work as a way to pass this settings to the editor and use them. Another option could be the use of "inline scripts" somehow. For the widgets screen we could probably just access the setting in the backend before adding the menu item and the customizer panel.

What do you think?

tellthemachines · 2019-07-24T04:44:33Z

I also wonder if we should make the settings work before merging.

Definitely we should make them work; I haven't touched that part yet because I was unsure if they should be disabled by default, particularly the widget ones that are already there, as it might be confusing for users to see them disappear suddenly.

We should have an option to show the hidden menu block

Is the menu block in yet? I thought it was still being worked on. I'm more than happy to set up an option for it 😄

tellthemachines · 2019-07-24T05:03:15Z

We should use "Widgets" as a single group for the two fields, and add more specific labels to the right of each checkbox. Here's a quick mockup:

OK so I've been playing around with this and if I add "Widgets" as a title to the settings section, it will be output as a h2 above the checkboxes. Otherwise I can add it as a title to the first of the settings fields, and it will look just like @kjellr 's screenshot but the text will just be inside a th. That doesn't seem right semantically.
Ideally, it should be added to the settings section as a h2 and restyled. Is it possible to override the default wp-admin styles from within the plugin though?

mapk · 2019-07-24T23:04:52Z

Definitely we should make them work; I haven't touched that part yet because I was unsure if they should be disabled by default, particularly the widget ones that are already there, as it might be confusing for users to see them disappear suddenly.

I believe this is okay. They do say they are (beta) so they can change and will change placement/visibility/etc. Especially now that we're placing these under "Experiments" it makes them feel much less complete.

Is the menu block in yet?

While the menu block is accessible if the user adds the block manually in the Code Editor, it needs some tidying up before we should make this easily available, I think.

Ideally, it should be added to the settings section as a h2 and restyled.

Can we make the markup look like @afercia's example above? Or is there something I'm missing?

tellthemachines · 2019-07-29T07:03:07Z

Can we make the markup look like @afercia's example above? Or is there something I'm missing?

I'm afraid @afercia's example isn't using the Settings API: https://github.com/WordPress/wordpress-develop/blob/master/src/wp-admin/options-discussion.php#L162-L173
There's no way to achieve that markup with the functions the API provides. But if, as per @youknowriad 's comment, we make widgets screen and legacy widget block a single option, that solves the problem for this particular section 😄

mapk · 2019-07-29T19:02:47Z

But if, as per @youknowriad 's comment, we make widgets screen and legacy widget block a single option, that solves the problem for this particular section

I'm all for this for a quick fix, but as new experiments get added we'll have to eventually solve this issue, correct?

talldan · 2019-08-05T09:51:47Z

lib/experiments-page.php

+ */
+function gutenberg_experiments_editor_settings( $settings ) {
+	$experiments_exist = get_option( 'gutenberg-experiments' );
+	return array(


I was wondering why so many e2e tests are failing in this branch. I think this is the cause. The $settings being passed in need to be merged with the array of new settings. You should be able to use array_merge.

talldan · 2019-08-05T09:52:28Z

packages/block-library/src/index.js

-			unstable__bootstrapServerSideBlockDefinitions( { [ name ]: metadata } ); // eslint-disable-line camelcase
-		}
-		registerBlockType( name, settings );
+		registerBlock( block );


nitpick, this and the one below could just be forEach( registerBlock )

mapk · 2019-08-05T23:18:12Z

I just took another look at this Experiments page again, and it looked good. Here's a screenshot for reference.

Selecting the checkbox for the widgets screen showed the Widgets screen option in the plugin menu. The Nav block option didn't produce the results I expected because as I went to a post, it appears I lost my ability to add any block to the editor. It's kind of weird and not sure if that's an issue with this PR, or just some artifact due to some rebasing that needs to happen. But I thought to mention it here anyways.

tellthemachines · 2019-08-06T04:58:35Z

The Nav block option didn't produce the results I expected because as I went to a post, it appears I lost my ability to add any block to the editor.

Hmm not sure why that would happen, but I've updated a few things and the e2e tests are passing so everything should now be fine 😅

talldan · 2019-08-06T07:21:48Z

packages/e2e-test-utils/src/enable-experimental-features.js

+	await Promise.all( features.map( async ( feature ) => {
+		await page.waitForSelector( feature );
+		await page.click( feature );
+		await page.click( '#submit' );


Instead of clicking submit for each feature, that could be done afterwards outside of the loop.

talldan

This is looking good!

The e2e test util could be improved in a follow up PR.

Would be great to update the those @params and @since version numbers before merging.

talldan · 2019-08-06T07:22:46Z

packages/e2e-test-utils/src/enable-experimental-features.js

+
+	await Promise.all( features.map( async ( feature ) => {
+		await page.waitForSelector( feature );
+		await page.click( feature );


There might be a need to check the existing value in case it already happens to be checked (e.g. by another test, or if there were a single set of tests that toggled the options on and off). There's some similar code in this utility:
https://github.com/WordPress/gutenberg/blob/master/packages/e2e-test-utils/src/toggle-screen-option.js#L17-L20

talldan · 2019-08-06T07:24:15Z

packages/e2e-test-utils/src/enable-experimental-features.js

+ *
+ * @param {Array} features Array of {string} selectors of settings to enable. Assumes they can be enabled with one click.
+ */
+export async function enableExperimentalFeatures( features ) {


I wonder if these features need to be disabled again after a test is run. 🤔

talldan · 2019-08-06T07:24:44Z

packages/block-library/src/index.js

 /**
 * Function to register core blocks provided by the block editor.
 *
+ * @param {boolean} enableLegacyWidgets     Optional. Editor setting to enable Legacy Widget Block.
+ * @param {boolean} enableMenu              Optional. Editor setting to enable Menu Block.


Looks like this was refactored and these two params don't seem to be needed.

yes, this should be removed.

talldan · 2019-08-06T07:40:18Z

packages/block-library/src/index.js

+/**
+ * Function to register experimental core blocks depending on editor settings.
+ *
+ * @param {Object} settings     Editor settings.


Would be good to remove the extra white space 😄

gziolo · 2019-08-06T07:43:54Z

packages/block-library/src/index.js

+ * registerExperimentalCoreBlocks( settings );
+ * ```
+ */
+export const registerExperimentalCoreBlocks = process.env.GUTENBERG_PHASE === 2 ? ( settings ) => {


Shouldn't we prefix it with __experimental as this is not meant to be a part of the public API?

See: https://github.com/WordPress/gutenberg/blob/master/docs/contributors/coding-guidelines.md#experimental-and-unstable-apis

noisysocks

Looks good and tests well! Great work on this @tellthemachines!

youknowriad · 2019-08-06T11:33:48Z

Nice work here. Thanks.

I noticed that the customizer "Widgets Blocks" panel is always visible. This panel should be tied to the "Enable Widgets Screen and Legacy Widget Block" setting.

tellthemachines · 2019-08-06T21:59:28Z

I noticed that the customizer "Widgets Blocks" panel is always visible. This panel should be tied to the "Enable Widgets Screen and Legacy Widget Block" setting.

Whoops. I'll fix that in a new PR.

* Gutenberg experiments settings page. * Address PR feedback. * Fix labels and heading semantics * UI improvements and disable by default. * Updated docs. * Address review feedback. * Changed feature flag logic * Remove check for test env * Merge experiments settings with existing settings. * Enable experimental blocks in test. * Prettify. * Docs updates * Remove extra whitespace. * Change function name.

tellthemachines requested review from aduth, TimothyBJacobs and youknowriad as code owners July 17, 2019 07:28

talldan reviewed Jul 17, 2019

View reviewed changes

lib/experiments-page.php Outdated Show resolved Hide resolved

tellthemachines added Needs Decision Needs a decision to be actionable or relevant Needs Design Feedback Needs general design feedback. labels Jul 17, 2019

talldan reviewed Jul 17, 2019

View reviewed changes

lib/experiments-page.php Outdated Show resolved Hide resolved

Soean reviewed Jul 17, 2019

View reviewed changes

lib/experiments-page.php Outdated Show resolved Hide resolved

lib/experiments-page.php Outdated Show resolved Hide resolved

lib/experiments-page.php Outdated Show resolved Hide resolved

talldan reviewed Jul 17, 2019

View reviewed changes

draganescu requested changes Jul 17, 2019

View reviewed changes

tellthemachines requested a review from draganescu July 18, 2019 00:42

swissspidy reviewed Jul 18, 2019

View reviewed changes

swissspidy added the Needs Accessibility Feedback Need input from accessibility label Jul 18, 2019

karmatosed removed Needs Accessibility Feedback Need input from accessibility Needs Design Feedback Needs general design feedback. labels Jul 19, 2019

draganescu previously approved these changes Jul 23, 2019

View reviewed changes

youknowriad previously requested changes Jul 23, 2019

View reviewed changes

noisysocks added [Type] Enhancement A suggestion for improvement. and removed Needs Decision Needs a decision to be actionable or relevant labels Jul 29, 2019

Address review feedback.

cc89a4e

tellthemachines force-pushed the add/plugin-experiments-settings-page branch from 942a686 to cc89a4e Compare August 2, 2019 04:11

tellthemachines added 2 commits August 2, 2019 16:17

Changed feature flag logic

f2daf40

Remove check for test env

b734519

talldan reviewed Aug 5, 2019

View reviewed changes

tellthemachines added 3 commits August 6, 2019 11:09

Merge experiments settings with existing settings.

3b643db

Enable experimental blocks in test.

a05ef88

Prettify.

11547aa

talldan reviewed Aug 6, 2019

View reviewed changes

noisysocks added this to the Gutenberg 6.3 milestone Aug 6, 2019

talldan approved these changes Aug 6, 2019

View reviewed changes

talldan reviewed Aug 6, 2019

View reviewed changes

Docs updates

221a65f

gziolo reviewed Aug 6, 2019

View reviewed changes

tellthemachines added 2 commits August 6, 2019 17:45

Remove extra whitespace.

13c7004

Change function name.

a51678d

noisysocks approved these changes Aug 6, 2019

View reviewed changes

tellthemachines merged commit b4c7054 into master Aug 6, 2019

tellthemachines mentioned this pull request Aug 6, 2019

Refactor experiments settings e2e tests #16922

Closed

talldan deleted the add/plugin-experiments-settings-page branch August 6, 2019 09:02

jorgefilipecosta mentioned this pull request Aug 6, 2019

Fix some problems in enableExperimentalFeatures e2e util function #16930

Merged

tellthemachines mentioned this pull request Aug 8, 2019

Enable customizer legacy widgets only if set #16956

Merged

5 tasks

epiqueras mentioned this pull request Nov 7, 2019

[WIP] Draft: Sync Editor React state with Yjs #18357

Closed

4 tasks

Gutenberg experiments settings page. #16626

Gutenberg experiments settings page. #16626

Conversation

tellthemachines commented Jul 17, 2019

Description

How has this been tested?

Screenshots

Types of changes

Checklist:

Soean left a comment

Choose a reason for hiding this comment

talldan Jul 17, 2019 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

noisysocks commented Jul 18, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tellthemachines commented Jul 19, 2019

kjellr commented Jul 19, 2019

mapk commented Jul 19, 2019

afercia commented Jul 19, 2019

youknowriad left a comment

Choose a reason for hiding this comment

tellthemachines commented Jul 24, 2019

tellthemachines commented Jul 24, 2019

mapk commented Jul 24, 2019

tellthemachines commented Jul 29, 2019

mapk commented Jul 29, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mapk commented Aug 5, 2019

tellthemachines commented Aug 6, 2019

Choose a reason for hiding this comment

talldan left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

noisysocks left a comment

Choose a reason for hiding this comment

youknowriad commented Aug 6, 2019

tellthemachines commented Aug 6, 2019

talldan Jul 17, 2019 •

edited