WordPress.org
Get WordPress

Making WordPress.org

Changeset 10078


Ignore:
Timestamp:
07/17/2020 09:15:33 PM (5 years ago)
Author:
ryelle
Message:

Plugin Directory: Improve feedback on block checker page

This restructures the page so the flow is more clear, adds clarity to what counts as a blocker, and adds more details to all flagged issues.

See #5303

File:
1 edited

Legend:

Unmodified
Added
Removed

  • sites/trunk/wordpress.org/public_html/wp-content/plugins/plugin-directory/shortcodes/class-block-validator.php

    r10071 r10078  
    4848                                self::maybe_send_email_plugin_added( $post );
    4949                                Plugin_Import::queue( $post->post_name, array( 'tags_touched' => array( $post->stable_tag ) ) );
     50                                echo '<div class="notice notice-success notice-alt"><p>' . __( 'Plugin added to the block directory.', 'wporg-plugins' ) . '</p></div>';
    5051                            } elseif ( 'remove' === $_POST['block-directory-edit'] ) {
    5152                                Tools::audit_log( 'Plugin removed from block directory.', $post->ID );
     53                                echo '<div class="notice notice-info notice-alt"><p>' . __( 'Plugin removed from the block directory.', 'wporg-plugins' ) . '</p></div>';
    5254                            }
    5355                        }
    … …  
    7880
    7981    /**
    80      * Validates readme.txt contents and adds feedback.
     82     * Render the form to add/remove the block from the directory.
     83     *
     84     * @param WP_Post $plugin     The post object representing this plugin.
     85     * @param bool    $has_errors Whether this plugin has errors preventing it from inclusion in the directory.
     86     */
     87    protected static function render_plugin_actions( $plugin, $has_errors ) {
     88        echo '<form method="post">';
     89        echo '<input type="hidden" name="plugin-id" value="' . esc_attr( $plugin->ID ) . '" />';
     90
     91        if ( self::plugin_is_in_block_directory( $plugin->post_name ) ) {
     92            echo wp_nonce_field( 'block-directory-edit-' . $plugin->ID, 'block-directory-nonce' );
     93            // translators: %s plugin title.
     94            echo '<p><button class="button button-secondary button-large" type="submit" name="block-directory-edit" value="remove">' . sprintf( __( 'Remove %s from Block Directory', 'wporg-plugins' ), $plugin->post_title ) . '</button></p>';
     95        } else if ( ! $has_errors ) {
     96            echo wp_nonce_field( 'block-directory-edit-' . $plugin->ID, 'block-directory-nonce' );
     97            // translators: %s plugin title.
     98            echo '<p><button class="button button-primary button-large" type="submit" name="block-directory-edit" value="add">' . sprintf( __( 'Add %s to Block Directory', 'wporg-plugins' ), $plugin->post_title ) . '</button></p>';
     99        }
     100
     101        echo '</form>';
     102    }
     103
     104    /**
     105     * Validates a block plugin to check that blocks are correctly registered and detectable.
    81106     *
    82107     * @param string $plugin_url The URL of a Subversion or GitHub repository.
    … …  
    92117            echo '<p>';
    93118            printf(
    94                 'Results for %1$s revision %2$s',
     119                // translators: %1$s is the repo URL, %2$s is a version number.
     120                __( 'Results for %1$s revision %2$s', 'wporg-plugins' ),
    95121                '<code>' . esc_url( $checker->repo_url ) . '</code>',
    96122                esc_html( $checker->repo_revision )
    … …  
    109135        }
    110136
     137        $has_errors = ! empty( $results_by_type['error'] );
     138        $has_warnings = ! empty( $results_by_type['warning'] ) || ! empty( $block_json_issues );
     139
     140        if ( $has_errors ) :
     141            ?>
     142            <div class="notice notice-error notice-alt">
     143                <p><?php _e( 'Some problems were found. They need to be addressed in order for your plugin to be included in the Block Directory.', 'wporg-plugins' ); ?></p>
     144            </div>
     145        <?php elseif ( $checker->slug ) : ?>
     146            <?php if ( self::plugin_is_in_block_directory( $checker->slug ) ) : ?>
     147                <div class="notice notice-info notice-alt">
     148                    <p><?php _e( 'This plugin is already in the Block Directory.', 'wporg-plugins' ); ?></p>
     149                </div>
     150            <?php elseif ( $has_warnings ) : ?>
     151                <div class="notice notice-info notice-alt">
     152                    <p><?php _e( 'You can add your plugin to the Block Directory.', 'wporg-plugins' ); ?></p>
     153                </div>
     154            <?php else : ?>
     155                <div class="notice notice-success notice-alt">
     156                    <p><?php _e( 'No issues were found. You can add your plugin to the Block Directory.', 'wporg-plugins' ); ?></p>
     157                </div>
     158            <?php endif; ?>
     159        <?php else : ?>
     160            <div class="notice notice-info notice-alt">
     161                <p>
     162                    <?php
     163                    printf(
     164                        __( 'Your plugin passed the checks, but only plugins hosted on WordPress.org can be added to the Block Directory. <a href="%s">Upload your plugin to the WordPress.org repo,</a> then come back here to add it to the Block Directory.', 'wporg-plugins' ),
     165                        esc_url( home_url( 'developers' ) )
     166                    );
     167                    ?>
     168                </p>
     169            </div>
     170            <?php
     171        endif;
     172
    111173        if ( $checker->slug ) {
    112174            $plugin = Plugin_Directory::get_plugin_post( $checker->slug );
    113175            if ( current_user_can( 'edit_post', $plugin->ID ) ) {
    114176                // Plugin reviewers etc
    115                 echo '<form method="post">';
    116177                echo '<h3>' . __( 'Plugin Review Tools', 'wporg-plugins' ) . '</h3>';
    117178                echo '<ul>';
    … …  
    120181                echo '</ul>';
    121182
    122                 echo wp_nonce_field( 'block-directory-edit-' . $plugin->ID, 'block-directory-nonce' );
    123                 echo '<input type="hidden" name="plugin-id" value="' . esc_attr( $plugin->ID ) . '" />';
    124                 echo '<p>';
    125                 if ( ! empty( $results_by_type['error'] ) ) {
    126                     // translators: %s plugin title.
    127                     printf( __( "%s can't be added to the block directory, due to errors in validation.", 'wporg-plugins' ), $plugin->post_title );
    128                 } else if ( self::plugin_is_in_block_directory( $checker->slug ) ) {
    129                     // translators: %s plugin title.
    130                     echo '<button class="button button-secondary button-large" type="submit" name="block-directory-edit" value="remove">' . sprintf( __( 'Remove %s from Block Directory', 'wporg-plugins' ), $plugin->post_title ) . '</button>';
    131                 } else {
    132                     // translators: %s plugin title.
    133                     echo '<button class="button button-primary button-large" type="submit" name="block-directory-edit" value="add">' . sprintf( __( 'Add %s to Block Directory', 'wporg-plugins' ), $plugin->post_title ) . '</button>';
    134                 }
    135                 echo '</p>';
    136                 echo '</form>';
     183                self::render_plugin_actions( $plugin, $has_errors );
    137184            } elseif ( current_user_can( 'plugin_admin_edit', $plugin->ID ) ) {
    138185                // Plugin committers
    139                 echo '<form method="post">';
    140186                echo '<h3>' . __( 'Committer Tools', 'wporg-plugins' ) . '</h3>';
    141187                echo '<ul>';
    … …  
    143189                echo '</ul>';
    144190
    145                 echo wp_nonce_field( 'block-directory-edit-' . $plugin->ID, 'block-directory-nonce' );
    146                 echo '<input type="hidden" name="plugin-id" value="' . esc_attr( $plugin->ID ) . '" />';
    147                 echo '<p>';
    148                 if ( ! empty( $results_by_type['error'] ) ) {
    149                     // translators: %s plugin title.
    150                     printf( __( "%s can't be added to the block directory, due to errors in validation.", 'wporg-plugins' ), $plugin->post_title );
    151                 } else if ( self::plugin_is_in_block_directory( $checker->slug ) ) {
    152                     // translators: %s plugin title.
    153                     echo '<button class="button button-secondary button-large" type="submit" name="block-directory-edit" value="remove">' . sprintf( __( 'Remove %s from Block Directory', 'wporg-plugins' ), $plugin->post_title ) . '</button>';
    154                 } else {
    155                     // translators: %s plugin title.
    156                     echo '<button class="button button-primary button-large" type="submit" name="block-directory-edit" value="add">' . sprintf( __( 'Add %s to Block Directory', 'wporg-plugins' ), $plugin->post_title ) . '</button>';
     191                self::render_plugin_actions( $plugin, $has_errors );
     192            }
     193        }
     194
     195        $output = '';
     196
     197        $error_types = array(
     198            'error'   => array(
     199                'title' => __( 'Fatal Errors', 'wporg-plugins' ),
     200                'description' => __( 'These issues must be fixed before this block can appear in the block directory.', 'wporg-plugis' ),
     201            ),
     202            'warning' => array(
     203                'title' => __( 'Recommendations', 'wporg-plugins' ),
     204                'description' => __( 'These are suggestions to improve your block. While they are not required for your block plugin to be added to the Block Directory, addressing them will help people discover and use your block.', 'wporg-plugins' ),
     205            ),
     206            'info'    => array(
     207                'title' => __( 'Notes', 'wporg-plugins' ),
     208                'description' => false,
     209            ),
     210        );
     211        foreach ( $error_types as $type => $labels ) {
     212            if ( empty( $results_by_type[ $type ] ) ) {
     213                // Print out the warning wrapper if we have block.json issues.
     214                if ( 'warning' !== $type || empty( $block_json_issues ) ) {
     215                    continue;
    157216                }
    158                 echo '</p>';
    159             }
    160         }
    161 
    162         $output = '';
    163 
    164         if ( empty( $results_by_type['error'] ) ) {
    165             $output .= '<h3>' . __( 'Success', 'wporg-plugins' ) . '</h3>';
    166             $output .= "<div class='notice notice-success notice-alt'>\n";
    167             if ( $checker->slug && self::plugin_is_in_block_directory( $checker->slug ) ) {
    168                 $output .= '<p>' . __( 'No problems were found. This plugin is already in the Block Directory.', 'wporg-plugins' ) . '</p>';
    169             } else {
    170                 $output .= '<p>' . __( 'No problems were found. Your plugin has passed the first step towards being included in the Block Directory.', 'wporg-plugins' ) . '</p>';
    171             }
    172             $output .= "</div>\n";
    173         } else {
    174             $output .= '<h3>' . __( 'Problems were encountered', 'wporg-plugins' ) . '</h3>';
    175             $output .= "<div class='notice notice-error notice-alt'>\n";
    176             $output .= '<p>' . __( 'Some problems were found. They need to be addressed before your plugin will work in the Block Directory.', 'wporg-plugins' ) . '</p>';
    177             $output .= "</div>\n";
    178         }
    179 
    180         $error_types = array(
    181             'error'   => __( 'Fatal Errors:', 'wporg-plugins' ),
    182             'warning' => __( 'Warnings:', 'wporg-plugins' ),
    183             'info'    => __( 'Notes:', 'wporg-plugins' ),
    184         );
    185         foreach ( $error_types as $type => $warning_label ) {
    186             if ( empty( $results_by_type[ $type ] ) ) {
    187                 continue;
    188             }
    189 
    190             $output .= "<h3>{$warning_label}</h3>\n";
     217            }
     218
     219            $output .= "<h3>{$labels['title']}</h3>\n";
     220            if ( $labels['description'] ) {
     221                $output .= "<p class='small'>{$labels['description']}</p>\n";
     222            }
    191223            $output .= "<div class='notice notice-{$type} notice-alt'>\n";
    192             foreach ( $results_by_type[ $type ] as $item ) {
     224            foreach ( (array) $results_by_type[ $type ] as $item ) {
    193225                // Only get details if this is a warning or error.
    194226                $details = ( 'info' === $type ) ? false : self::get_detailed_help( $item->check_name, $item );
    … …  
    232264    public static function get_detailed_help( $method, $result ) {
    233265        switch ( $method ) {
    234             // These don't need more details.
    235266            case 'check_readme_exists':
     267                return [
     268                    __( 'All plugins need a readme.txt file.', 'wporg-plugins' ),
     269                    sprintf(
     270                        '<a href="%1$s">%2$s</a>',
     271                        esc_url( home_url( 'developers/#readme' ) ),
     272                        __( 'Learn more about readmes.', 'wporg-plugins' )
     273                    ),
     274                ];
    236275            case 'check_license':
     276                return [
     277                    __( 'Plugins should include a GPL-compatible license in either readme.txt or the plugin headers.', 'wporg-plugins' ),
     278                    sprintf( '<a href="https://developer.wordpress.org/plugins/wordpress-org/detailed-plugin-guidelines/#1-plugins-must-be-compatible-with-the-gnu-general-public-license">%s</a>', __( 'Learn more about readmes.', 'wporg-plugins' ) ),
     279                ];
    237280            case 'check_plugin_headers':
    238                 return false;
    239             // This is a special case, since multiple values may be collapsed.
    240             case 'check_block_json_is_valid':
    241                 return false;
     281                return sprintf( '<a href="https://developer.wordpress.org/plugins/plugin-basics/header-requirements/">%s</a>', __( 'Learn more about plugin headers.', 'wporg-plugins' ) );
    242282            case 'check_block_tag':
    243283                return __( 'The readme.txt file must contain the tag "block" (singular) for this to be added to the block directory.', 'wporg-plugins' );
    … …  
    254294                    __( 'In order to work in the Block Directory, a plugin must register a block. Generally one per plugin (multiple blocks may be permitted if those blocks are interdependent, such as a list block that contains list item blocks).', 'wporg-plugins' ),
    255295                    __( 'If your plugin doesn’t register a block, it probably belongs in the main Plugin Directory rather than the Block Directory.', 'wporg-plugins' ),
    256                     sprintf( '<a href="TUTORIAL">%s</a>', __( 'Learn how to create a block.' ) ),
     296                    sprintf( '<a href="https://developer.wordpress.org/block-editor/tutorials/create-block/">%s</a>', __( 'Learn how to create a block.' ) ),
    257297                ];
    258298            case 'check_for_block_json':
    … …  
    274314                    __( 'Example: <code>my-plugin/my-custom-block</code>', 'wporg-plugins' ),
    275315                ];
     316            case 'check_for_single_parent':
     317                return __( 'Block plugins should contain a single main block, which is added to the editor when the block is installed. If multiple blocks are used (ex: list items in a list block), the list items should set the `parent` property in their `block.json` file.', 'wporg-plugins' );
     318            // This is a special case, since multiple values may be collapsed.
     319            case 'check_block_json_is_valid':
     320                return false;
    276321        }
    277322    }
Note: See TracChangeset for help on using the changeset viewer.