diff --git a/core/modules/outside_in/outside_in.api.php b/core/modules/outside_in/outside_in.api.php index 913036f..ba88f0a 100644 --- a/core/modules/outside_in/outside_in.api.php +++ b/core/modules/outside_in/outside_in.api.php @@ -12,33 +12,36 @@ * * @section sec_api The API: the form in the Settings Tray * - * By default, every block will show their built-in form in the Settings Tray. + * By default, every block will show its built-in form in the Settings Tray. * However, many blocks would benefit from a tailored form which either: - * - limits the form to only the form items that affect the content of the - * rendered block, or - * - adds additional form items to edit configuration that is rendered by the + * - Limits the form items displayed in the Settings Tray to only items + * that affect the content of the rendered block, or + * - Adds additional form items to edit configuration that is rendered by the * block. - * This results in a better experience: the Settings Tray form always allows the - * user to change what is rendered by the block. + * These can be used to provide a better experience, so that the Settings Tray + * only displays what the user will expect to change when editing the block. * - * Each block plugin can specify which form to use in the off-canvas dialog: + * Each block plugin can specify which form to use in the Settings Tray dialog + * in their plugin annotation: * @code * forms = { * "off_canvas" = "\Drupal\some_module\Form\MyBlockOffCanvasForm", * }, * @encode * - * In rare cases, a block's content cannot be modified — for example the page - * title, main content and help blocks. In these cases, you can opt-out: + * In some cases, a block's content is not configurable (for example, the title, + * main content, and help blocks). Such blocks can opt out of + * providing an off-canvas form: * @code * forms = { * "off_canvas" = FALSE, * }, * @encode * - * Finally, blocks that do not provide "off-canvas forms" will automatically - * have it set to their plugin class. For example, the "Powered by Drupal" block - * plugin (\Drupal\system\Plugin\Block\SystemPoweredByBlock) automatically gets + * Finally, blocks that do not specify an off-canvas form using the annotations + * above will automatically have it set to their plugin class. + * For example, the "Powered by Drupal" block plugin + * (\Drupal\system\Plugin\Block\SystemPoweredByBlock) automatically gets * this added to its annotation: * @code * forms = { diff --git a/core/modules/outside_in/outside_in.module b/core/modules/outside_in/outside_in.module index e7348d9..20bc350 100644 --- a/core/modules/outside_in/outside_in.module +++ b/core/modules/outside_in/outside_in.module @@ -101,7 +101,6 @@ function outside_in_preprocess_block(&$variables) { // regions immediately when the page loads. When latency is high, this will // cause flicker. Therefore, for now, we choose to duplicate some logic to // guarantee a smooth experience. - // This is an implementation detail that may change in the future. // @see \Drupal\outside_in\Access\BlockPluginHasOffCanvasFormAccessCheck /** @var \Drupal\outside_in\Access\BlockPluginHasOffCanvasFormAccessCheck $access_checker */ $access_checker = \Drupal::service('access_check.outside_in.block.off_canvas_form'); @@ -122,7 +121,8 @@ function outside_in_preprocess_block(&$variables) { * Alters the 'contextual' toolbar tab if it exists (meaning the user is allowed * to use contextual links) and if they can administer blocks. * - * @todo Remove the "administer blocks" requirement in https://www.drupal.org/node/2822965 + * @todo Remove the "administer blocks" requirement in + * https://www.drupal.org/node/2822965 * @see contextual_toolbar() */ function outside_in_toolbar_alter(&$items) { @@ -154,15 +154,17 @@ function outside_in_toolbar_alter(&$items) { */ function outside_in_block_alter(&$definitions) { foreach ($definitions as &$definition) { - // If the block plugin already defines an 'off_canvas' form, there's nothing - // to do. + // If a block plugin already defines its own off_canvas form, + // use that form instead of specifying one here. if (isset($definition['forms']['off_canvas'])) { continue; } switch ($definition['id']) { - // Use specialized off-canvas forms when they're available. - // @todo move these into the corresponding block plugin annotations in https://www.drupal.org/node/2896356 + // Use specialized forms for certain blocks that do not yet provide + // the form with their own annotation. + // @todo move these into the corresponding block plugin annotations in + // https://www.drupal.org/node/2896356 case 'system_menu_block': $definition['forms']['off_canvas'] = SystemMenuOffCanvasForm::class; break; @@ -173,7 +175,8 @@ function outside_in_block_alter(&$definitions) { // No off-canvas form for the page title block, despite it having // contextual links: it's too confusing that you're editing configuration, // not content, so the title itself cannot actually be changed. - // @todo move these into the corresponding block plugin annotations in https://www.drupal.org/node/2896356 + // @todo move these into the corresponding block plugin annotations in + // https://www.drupal.org/node/2896356 case 'page_title_block': $definition['forms']['off_canvas'] = FALSE; break; @@ -184,7 +187,8 @@ function outside_in_block_alter(&$definitions) { $definition['forms']['off_canvas'] = FALSE; break; - // Otherwise fall back to the built-in form for the block plugin. + // Otherwise, use the block plugin's normal form rather than + // a custom form for Outside In. default: $definition['forms']['off_canvas'] = $definition['class']; break; diff --git a/core/modules/outside_in/tests/modules/outside_in_test/src/Form/OffCanvasFormAnnotationIsClassBlockForm.php b/core/modules/outside_in/tests/modules/outside_in_test/src/Form/OffCanvasFormAnnotationIsClassBlockForm.php index 2136615..055bf87 100644 --- a/core/modules/outside_in/tests/modules/outside_in_test/src/Form/OffCanvasFormAnnotationIsClassBlockForm.php +++ b/core/modules/outside_in/tests/modules/outside_in_test/src/Form/OffCanvasFormAnnotationIsClassBlockForm.php @@ -8,7 +8,7 @@ /** * @see \Drupal\outside_in_test\Plugin\Block\OffCanvasFormAnnotationIsClassBlock */ -class OffCanvasFormAnntationIsClassBlockForm extends PluginFormBase { +class OffCanvasFormAnnotationIsClassBlockForm extends PluginFormBase { /** * The block plugin. diff --git a/core/modules/outside_in/tests/modules/outside_in_test/src/Plugin/Block/OffCanvasFormAnnotationIsClassBlock.php b/core/modules/outside_in/tests/modules/outside_in_test/src/Plugin/Block/OffCanvasFormAnnotationIsClassBlock.php index 41af9dc..1fd9aff 100644 --- a/core/modules/outside_in/tests/modules/outside_in_test/src/Plugin/Block/OffCanvasFormAnnotationIsClassBlock.php +++ b/core/modules/outside_in/tests/modules/outside_in_test/src/Plugin/Block/OffCanvasFormAnnotationIsClassBlock.php @@ -11,7 +11,7 @@ * id = "outside_in_test_class", * admin_label = "Settings Tray test block: forms[off_canvas]=class", * forms = { - * "off_canvas" = "\Drupal\outside_in_test\Form\OffCanvasFormAnntationIsClassBlockForm", + * "off_canvas" = "\Drupal\outside_in_test\Form\OffCanvasFormAnnotationIsClassBlockForm", * }, * ) */ diff --git a/core/modules/outside_in/tests/src/Functional/OutsideInTest.php b/core/modules/outside_in/tests/src/Functional/OutsideInTest.php index 1cefffa..9ed9301 100644 --- a/core/modules/outside_in/tests/src/Functional/OutsideInTest.php +++ b/core/modules/outside_in/tests/src/Functional/OutsideInTest.php @@ -6,7 +6,7 @@ use Drupal\Tests\BrowserTestBase; /** - * Testing opening and saving block forms in the off-canvas dialog. + * Tests opening and saving block forms in the off-canvas dialog. * * @group outside_in */ @@ -37,7 +37,7 @@ protected function getBlockSelector(Block $block) { * Tests the three possible forms[off_canvas] annotations: class, FALSE, none. * * There is also functional JS test coverage to ensure that the two blocks - * that support Settings Tray (the "class" & "none" cases) do work correctly. + * that support Settings Tray (the "class" and "none" cases) do work correctly. * * @see OutsideInBlockFormTest::testBlocks() */