Update the UI texts for the Custom Block module

On it

Not clear how much change should I make, maybe I'm just overthinking it, some detailed feedback would be appreciated. Leaving unassigned, maybe someone with more documentation experience solves it easily.

I took a look at this and have a few comments:

1. The help text doesn't reference the fact it's custom blocks, not sure if this is relevant but if the titles use the name then maybe the help text should also reference this.
2. http://drupal8.dev/admin/structure/block/block-content -> has the title "Custom block library" the url doesn't reference a library or custom. Maybe this should be another issue all together.
3. http://drupal8.dev/admin/structure/block/block-content/types -> similar to above, block-content doesn't make sense considering it's a library.

Apparently this needs to be "rc deadline" because it changes translatable UI text strings. See https://groups.drupal.org/node/484788

The release candidate came out yesterday, so the deadline was missed. So... see https://www.drupal.org/core/d8-allowed-changes ... under Evaluating, item 4:

Changes the data model (upgrade path), translatable strings, markup, CSS, user interfaces, render array structures, third-party libraries, etc.: postpone it to 8.1.x.

So unless we really need to ask for special committer discretion here, this needs to be postponed to 8.1.x. In which case we cannot work on it for a few months and so I am going to at least for the moment un-assign it. Thanks for your interest though!

- Barcelona2015, rc deadline

What do you think of these texts ?

For the "Blocks" tab :

This page provides a list of all custom blocks on the site and allows you to create, edit, and delete custom blocks of each custom block type you have defined, from the Custom block library page.

For the "Types" tab :

This page provides a list of all custom block types on the site and allows you to create and edit custom block types with fields and display settings. Create blocks of each type on the Block library page.

I have not taken #6 into account, because it seems that the title is for the entire section

This is may be a more general issue across Drupal but "Add" and "Create" are being used interchangeably here although they are not synonyms. I.e. the "Add custom block" and "Add custom block type" buttons and their target forms/pages aren't used to add blocks (which implies that they could be being imported from elsewhere) but instead to create new blocks/block types.

I mention this because while the changed page text in the #11 patch is fine as far as it goes, the use of the word "create" ("allows you to create...") there and in the hook_help() text is inconsistent with the button actions and page titles, which use the word "Add."

I think it would be best to make the action verb 'create' rather than 'add' but, if left at 'add' the help/description text should be consistent (IMO).

I have no strong opinion on "create" vs. "add" except that we should probably use the same terminology in the Help as we do in the UI, so if the button/link says "add", the help should also say "add", right?

Regarding #11, I like the Types text, but not the Blocks text quite as much... I found it to be confusing. It seems to be referring to itself rather than pointing out to go to the Types page to define types?

Screen shots would also be helpful for the next review, so we can see the tabs/help/buttons/links in context without having to start up our own instance of simplytest.me etc. Thanks!

This is what I did :

• replaced "create" with "add"
• removed mention to "library" as it doesn't improve comprehension
• tried to name more cleary "Block types page" and "Blocks page" without "custom", to recall the tab titles
• added sceenshots.

What do you think ?

Is 'library' used here because it is referencing created 'custom blocks'? Why not use 'list' instead or just 'Custom blocks'?

Just a question: Isn't this just another 'type' that can be created with fields like comments, content, ... and once create a list of comments, content is viewable.

What about this ?

Good! I like the fact that now the help text actually matches the UI.

I had one moment of "huh, what??" when I read the help text though, due to punctuation:

This page provides a list of all custom blocks on the site and allows you to add, edit, and delete custom blocks of each custom block type you have defined, from the Block types page.

So what this is trying to say is that you can (a) add, edit, delete blocks here and (b) if you want to define a custom block type, you need to go to the Block types page. But due to the punctuation, when I read the end of this sentence, my first thought was that I had to go to the Block types page in order to add/edit/delete blocks.

I think it would be clearer if this was made into two sentences, more like the help you have in the patch for the Types page:

This page provides a list of all custom block types on the site and allows you to add, edit, and delete custom block types with fields and display settings. Then you can add each type of block on the Blocks page.

And as a note... The issue summary mentions the hook_help text, so we probably also need to look at the text on:
- The main Block and Custom Block help pages (admin/help and click on Block or Custom Block)
- The Block layout page help text at the top
and make sure it is all consistent.

Also the issue summary suggests changing the UI text and not the help... I don't care too much which we do as long as they are consistent, but the issue summary needs an update if we're doing it this way.

This page provides a list of all custom blocks on the site and allows you to add, edit, and delete custom blocks of each custom block type you have defined, from the Block types page.

splitted text into two sentences.

Yes, this reads much better. Thanks!

So, I went back to the issue summary, and also started up simplytest.me to look at what the help and pages look like for a site, with this patch. There are still many inconsistencies between the UI text and the help text:

• admin/help/block_content (the Custom Block help page) says:
  

  Users with the Administer blocks permission can create and edit custom block types with fields and display settings, from the Custom block types page in the Custom block library.
  ...
  Users with the Administer blocks permission can create, edit, and delete custom blocks of each custom block type you have defined, from the Custom block library page. Custom blocks are shown in the Place blocks list on the Block layout page...

  Links:
  - Custom block types => admin/structure/block/block-content/types
  - Custom block library => admin/structure/block/block-content
  - Block layout page => admin/structure/block

• admin/structure/block/block-content:
  - The page title of this page is "Custom block library", which is also the tab title.
  - The sub-tab navigation title is simply "Blocks".
  - The button says "Add custom block"
  - The type column is called "Block type"
  - The help at the top of the page says:

  This page provides a list of all custom blocks on the site and allows you to add, edit, and delete custom blocks of each custom block type you have defined. You can manage block types from the Block types page.

  Links:
  - Block types page => admin/structure/block/block-content=

• admin/structure/block/block-content/types:
  - The page title is still "Custom block library", which is also the tab title.
  - The sub tab navigation title is simply "Types".
  - The button says "Add custom block type"
  - The types column is called "Block type"
  - The help at the top of the page says:

  This page provides a list of all custom block types on the site and allows you to add, edit, and delete custom block types with fields and display settings. Then you can add each type of block on the Blocks page.

  Links:
  - Blocks page => admin/structure/block/block-content

• admin/structure/block
  - The page title here is "Block layout".

Can you spot all the inconsistencies? There are a lot... Here is a list of what I think needs to be updated... at least these are my suggestions:

1. Whenever we refer to or link to admin/structure/block/block-content, we should call it "the Blocks page in the Custom block library".
2. Whenever we refer to or link to admin/structure/block/block-content/types, we should call it the "the Block types page in the Custom block library".
3. We should also change the sub-tab title on admin/structure/block/block-content/types to say "Block types" instead of just "Types".
4. Whenever we refer to or link to admin/structure/block, we should call it "the Block layout page".
5. I think that the help on admin/structure/block/block-content should say something to let you know that after creating a custom block, it will appear in the Place blocks list on the block layout page (with a link to that page). This is currently missing.
6. I think that in most help text, we do not include the word "page" inside the link text, so when making links in help do something like "the Foo bar page", not "the Foo bar page" or "the Foo bar page". This is also inconsistent across the various help texts mentioned above.

Thoughts?

Peezy & I are working on this at the Boston Sprint Weekend.

@jhodgdon What do you think about changing the button from "Save block" to "Save and Place Block" for your issue (#5) below:

I think that the help on admin/structure/block/block-content should say something to let you know that after creating a custom block, it will appear in the Place blocks list on the block layout page (with a link to that page). This is currently missing.

Adding a note that @hosttor is helping as well.

This addresses number 3 above

This patch is for 1, 2, 4, and 6.

...and both of the patches together.

It works as #28 said

Patch (update_ui_texts_customs_block-2572545-28) applied to Acquia desktop dev (dry run):

Problems completing. Is this supposed to be preceded by other patches?

beanworks, what do you mean by "problems completing"? As you can see, the patch applied and passed testing in #28. Oh, just saw the attached image. Are you applying to 8.1.x?

Thanks for the patches and comments!

So...

Regarding comment #24, I don't think that changing the save button on the configure blocks page to say "Save and place block" is relevant to this particular issue at all. If you want to make that suggestion for Drupal Core, please make a separate issue. we try to keep issues focused on one thing, and this one is about the "custom block" functionality, not about the generic block configure and place functionality. And this change would not help to address item #5 in comment #20, which is also about the custom block functionality and not about the configure block forms.

Regarding the patch in #28, I do not believe that it fixes the problems identified in #20. To whomever creates the next patch, I will suggest that you read #20 carefully, and then before submitting your patch, you should go to the 4 pages that are mentioned in #20 and make sure that all references on those pages are updated to the 6 points mentioned in #20. They aren't in this patch.

Thanks!

Assigning to me. Will look at patch in #19 and comments in #20.

I guess this patch matches the 6 points mentioned in #20
Concerning point #5, I suggested :

Blocks in the block library belong to Custom block types, each with its own fields and display settings. After creating a block, it will appear in the blocks list on the Block layout page, then you can place it in a region.

I think this all looks very good now, thanks! The top-of-page help, page names, table headers, and tab names are all consistent with each other within the Custom Blocks module UI now.

So, let's just fix a couple of minor grammatical/wording/accuracy issues introduced by the patch (or pre-existing):

a)

The Custom Block module allows you to create custom block types and content-containing blocks, and provides a Blocks page in the Custom block library listing all of them.

- The word "them" at the end of this sentence is ambiguous: it could be referring to blocks or block types.
- I think "a Blocks page" should be "the Blocks page"
- Saying that the Blocks page just "lists" the blocks is kind of misleading. It's a page you can use to manage them.

So I think this could be worded better. Maybe something like:

... allows you to create and manage custom block types and content-containing blocks from the Custom block library.

This would link to the Blocks page within the library, but the Block types page is linked there, so I think it would get across the point that you can manage both types and blocks?

b)

Users with the Administer blocks permission can create, edit, and delete custom blocks of each custom block type you have defined,

The wording here is weird. It starts with "Users" and then says "you have defined". Probably would be better to say something like
... of each defined custom block type, ...

c)

Custom blocks are shown in the Place blocks list on the Block layout page...

After creating a block, it will appear in the blocks list on the Block layout page, then you can place it in a region.

There is no "blocks" or "Place blocks" list on the Block layout page. There is only a list that appears if you click on "Place block". So these seem kind of misleading.

I think these two areas would be better if they did something more like what is in this help:

After creating a block, place it in a region from the Block layout page.

(maybe with the addition of "you can" or something like that.

Added the patch with above changes.
Interdiff added.

+++ b/core/modules/block_content/block_content.links.task.yml
@@ -7,7 +7,7 @@ block_content.list_sub:
+  title: Block types

don't you think it needs quotes. i may be wrong.

My feedback in #41 (a) was not addressed in this patch, or at least the interdiff doesn't show that it was fixed, as far as I can see.. (c) is not either, at least not completely.

Please read the reviews and if you don't understand what is being asked, rather than making a patch, ask a question. Thanks!

Added the patch as per the comment #41.

So.. I started from my previous patch at #40 and applied suggestions from #41.

@harsha012 : I guess you get wrong code with a copy paste, I found bad Urls and some "em" tags disappeared. Then I found out some code was missing from my previous patch, I guess you had things both in git working and staging areas and your git diff didn't catch everything.

@jhodgdon : I do not answer your interrogations, because I lack judgment :-), but mostly because I tried to strictly apply suggestions from #41 and put this patch back on track.

YES, thanks. This all looks much better to me! Assuming the bot agrees...

Changing component here. This is not really "documentation".

+++ b/core/modules/block_content/block_content.module
@@ -18,22 +18,22 @@ function block_content_help($route_name, RouteMatchInterface $route_match) {
+      $output .= '<p>' . t('The Custom Block module allows you to create and manage custom <em>block types</em> and <em>content-containing blocks</em> from the <a href = ":block-library" >Custom block library<a/>. Custom block types have fields; see the <a href=":field-help">Field module help</a> for more information. Once created, custom blocks can be placed in regions just like blocks provided by other modules; see the <a href=":blocks">Block module help</a> page for details. For more information, see the <a href=":online-help">online documentation for the Custom Block module</a>.', array(':block-library' => \Drupal::url('entity.block_content.collection'), ':block-content' => \Drupal::url('entity.block_content.collection'), ':field-help' => \Drupal::url('help.page', array('name' => 'field')), ':blocks' => \Drupal::url('help.page', array('name' => 'block')), ':online-help' => 'https://www.drupal.org/documentation/modules/block_content')) . '</p>';

Why is it 'Custom block library' in the link text, but 'custom block library' when not linked. I'd expect 'custom block' all the time since we don't treat 'block' by itself as a proper noun.

Done. Please review.

Normally, in UI text such as help, if we make a link to a particular page, we use the exact page name as shown in the UI when you go to the page. The page is called "Custom block library", so I think when linking to that page it should be capitalized.

However it should probably say

Custom block library page

Is that the reason that automated test fails ?

Should I rename patch #51 to #59 and set "Needs review" again ?

Can we add the word "page" in there, possibly in several places, as noted in #57?

Sure.
(I started from #51 to add "page")

Looks good. However, there are now two lines in this patch where in the help, "Custom block library" is capitalized instead of being just "custom block library" even though it is not a link.

1. +++ b/core/modules/block_content/block_content.module
   @@ -18,22 +18,22 @@ function block_content_help($route_name, RouteMatchInterface $route_match) {
   +      $output .= '<p>' . t('The Custom Block module allows you to create and manage custom <em>block types</em> and <em>content-containing blocks</em> from the <a href = ":block-library" >Custom block library<a/> page. Custom block types have fields; see the <a href=":field-help">Field module help</a> for more information. Once created, custom blocks can be placed in regions just like blocks provided by other modules; see the <a href=":blocks">Block module help</a> page for details. For more information, see the <a href=":online-help">online documentation for the Custom Block module</a>.', array(':block-library' => \Drupal::url('entity.block_content.collection'), ':block-content' => \Drupal::url('entity.block_content.collection'), ':field-help' => \Drupal::url('help.page', array('name' => 'field')), ':blocks' => \Drupal::url('help.page', array('name' => 'block')), ':online-help' => 'https://www.drupal.org/documentation/modules/block_content')) . '</p>';
   

   here's one

2. +++ b/core/modules/block_content/block_content.module
   @@ -18,22 +18,22 @@ function block_content_help($route_name, RouteMatchInterface $route_match) {
   +      $output = '<p>' . t('Each block type has its own fields and display settings. Create blocks of each type on the <a href=":block-library">Blocks</a> page in the Custom block library.', array(':block-library' => \Drupal::url('entity.block_content.collection'))) . '</p>';
   

   Here's the other.

Here, are #62 changes over #61 patch.

Please, ignore preovious patch, I've uncommited changes from other issues and I'm mixed them (so sorry).

This is the patch.

changed Custom block library to custom block library where there is no link. Please verify it once.

+++ b/core/modules/block_content/block_content.module
@@ -18,22 +18,22 @@ function block_content_help($route_name, RouteMatchInterface $route_match) {
+      $output .= '<dd>' . t('Users with the <em>Administer blocks</em> permission can create and edit custom block types with fields and display settings, from the <a href=":types">Block types</a> page in the Custom block library. For more information about managing fields and display settings, see the <a href=":field-ui">Field UI module help</a>.', array(':types' => \Drupal::url('entity.block_content_type.collection'), ':field-ui' => $field_ui)) . '</dd>';

This still says "Custom block library". So does another page. So that last patch is not good. I didn't look at the other two. Please why are you all adding multiple patches to this issue? One at a time!

lets see if this interdiff works:
git diff --color-words

slightly better maybe.

--color-words is only good for looking at things in your terminal. Please don't use it for making interdiff files, as they're not readable online. You need to just make regular interdiff files.

Anyway, the latest patch looks good, thanks!

Committers: I am not sure what the string change deadline is for the Beta cycle, but if that hasn't passed, I think it would be good to consider this for 8.1.x as well as 8.2.x.

Committed/pushed to 8.2.x and cherry-picked to 8.1.x. Thanks!