Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.
Updated: Comment #0
This issue is a part of #1908570: [meta] Update or create hook_help() texts for D8 core modules.
Guidelines: https://drupal.org/node/632280
See also: #2029731: Improve help for blocks module
Comment | File | Size | Author |
---|---|---|---|
#26 | 2062761-custom-block-help-26.patch | 2.86 KB | jhodgdon |
#22 | 2062761-custom-block-hook-help-22.patch | 3.23 KB | tim-e |
#10 | 2062761-add-hook-help-custom-block-1.patch | 4.2 KB | tim-e |
#8 | 2062761-add-hook-help-custom-block.patch | 4.88 KB | tim-e |
#7 | 2062761-add-hook-help-custom-block.patch | 4.88 KB | tim-e |
Comments
Comment #1
larowlanSplitting from #2062439: Provide listing of custom block entities to keep the changes there in scope
Comment #3
xjm#1: custom-block-help.1.patch queued for re-testing.
Comment #4
jhodgdonEntirely missing hook_help() is a critical issue (jumped the docs gate) as per catch.
A few comments on the patch:
a) It seems like the hook_help() for the Block module should mention the custom blocks module, rather than just taking the section out about creating custom blocks.
b) The Custom Block module help's About section can call them "blocks" not "boxes of content" and reference the Block module help for more information about blocks in general.
c) The Uses section seems to contradict itself. First it says you administer these things on the Custom Blocks page, and then later on it says they're on the Blocks page. ??? Either it's wrong or it's confusing, or both.
Comment #5
larowlannot as confusing as the UI apparently #2062715: [META] Many UI/UX issues with custom blocks.
Comment #6
alexpottNeeds a reroll now #2062439: Provide listing of custom block entities has landed
Comment #7
tim-e CreditAttribution: tim-e commentedHere is another pass at this taking into consideration the comments from #4.
Comment #8
tim-e CreditAttribution: tim-e commentedSorry about that, had the wrong help URL, fixed.
Comment #10
tim-e CreditAttribution: tim-e commentedOk here is another pass at this.
Comment #11
pameeela CreditAttribution: pameeela commented@tim-e, this looks good!
Just two comments.
I'd change this to:
'Users with the Administer blocks permission can add custom blocks, which are then listed on the Blocks administration page. Once created, custom blocks behave just like default and module-generated blocks. You can also create custom block types, with their own fields and display settings. See Custom blocks.'
Change the second instance of 'custom block content' to just 'custom blocks'.
Comment #12
jhodgdonAlso, when referring to the module, say:
... the Custom Blocks module ...
And when linking to the help page for another module, the link text should be "the help page for the Foo module".
And... What's a "default" block, as opposed to a "module-generated" block? I think all blocks come from modules?
Comment #13
catchComment #14
lostkangaroo CreditAttribution: lostkangaroo commentedLooking into custom_block last night I noticed that a hook_help had been added with #2062439: Provide listing of custom block entities. So now this becomes an update task.
Comment #15
batigolixComment #16
jhodgdonifrik decided to close #2029731: Improve help for blocks module as a duplicate, so the scope of this issue has now expanded to be both block and custom_block modules together. Make sure to review and fix both!
Alternatively, you can open up that other issue again and move the part of the patch here dealing with block.module to that issue.
Comment #17
ifrikIt would actually make more sense to treat the two issues as separate, and I'm happy to open #2029731: Improve help for blocks module again.
Unfortunately the patch in #10 fails for me (on line 14?), so I can't see what's already done, and/or what could be moved to a separate patch for blocks itself.
Comment #18
jhodgdonOK, go ahead and open up the other issue, change the title here, and put the other issue back on the meta-issue. :)
If you open the patch file in #10 in your browser, you can see that the line that was changed was in Uses:
This change is not grammatically correct and it fails to call the module "Custom Blocks" (note capitalization), but something like it should go into the Block module.
Comment #19
ifrikTitle changed so that this issue only deals with custom blocks, while #2029731: Improve help for blocks module will deal with blocks.
Comment #20
jhodgdonSo we need to remove the Blocks module section from the patch above, and there have been quite a few review comments above.
Comment #21
tim-e CreditAttribution: tim-e commentedComment #22
tim-e CreditAttribution: tim-e commentedIve removed the 'block' help from the patch and also addressed all the feedback since #10. I think I have covered everything but I suspect there might be some more work needed on the wording of the help text.
Comment #23
jhodgdonHey, sorry this took me so long to review! I'm just catching up from the help sprint at Prague...
This patch seems to have gotten rid of the help for page 'admin/structure/block/custom-blocks/types' -- was that intentional?
Other than that, it looks pretty good! A few small things:
a) The parens on the sentence about Blocks in the About can probably be removed.
b) I don't think the Block module tells about *creating* blocks. Isn't that more about managing blocks, and this module (custom blocks) or other modules do the creating?
c) There is no link to the on-line docs page for this module. See guidelines at
https://drupal.org/node/632280
d) The first Uses topic refers to some "administration pages" but I think it is just one page?
e) I don't think we need to say the "Once created... behave just like module-generated blocks" sentence twice?
Thanks!
Comment #24
ifrikThanks, there is so much more in custom blocks then I expected :)
1) Picking up on the comments in #10:
a) and b): @jhodgdon 's comment is correct. The block module is only about placing and mananging blocks. See #2029731: Improve help for blocks module for the proposed help text.
How about rewriting the about section without the brackets to something like this?
The Custom Block module allows you to create blocks of content. Once created, they behave just like module-generated blocks. For more information on placing and managing blocks see the <link>Blocks module help page</link>.
2) I'm not completely sure about the wording "module-generated". Would we call a block that's generated by Views be "module generated"? Alternatively you could say something like "automatically generated". The main point we need to bring accross here is that there are blocks that are made somewhere else, or so.
2) "Listing custom blocks and types" - Maybe as first item under Uses, we should describe the Custom block library as the place that lists all custom blocks and types, and from where you can add blocks and types. That's also because the pages to add blocks and types, don't actually show up in the admin menu,.
3) "Creating blocks": Instead of saying that "Once created, they behave like module generated blocks", I would be more specific. Maybe:
Once created, custom blocks are listed on the <link>Block Layout page</link> where they can be placed and managed like [other/module/automatically generated] blocks.
4) "Creating custom block types". Maybe split that into two sentences. First: the types can be created on the Custom block types page. It doesn't need the "administration" in there.
And second: saying that once you have created a custom block, you can add and manage fields and change its display settings in the Types listing of the Custom Block Library. With a link to the Field and Field UI pages. (See the Link module for standard wording.
5) I've got a second button to add a block type in the types list. Any idea whether that is a bug, or whether that button is supposed to do something different?
Comment #25
larowlanI think its no-longer clear from #24 and #23 what the remaining tasks are here, they seem to conflict.
Can we get an issue summary update of the remaining tasks.
Comment #26
jhodgdonOK... I decided it was easier just to make a new patch than to make a list of what needed to be done.
So this is a clean patch that only changes the main module help (previous patches had other changes, which are not desirable), and I think it addresses all the concerns above. I do not think an interdiff is useful at this point, since every line in this patch is different from previous patches.
Comment #26.0
jhodgdonUpdated issue summary.
Comment #27
jhodgdonI also updated the issue summary, which was quite innacurate at this point. It is now just a clean summary saying we need to update the help according to the guidelines.
Comment #28
batigolixLinks are okay & text is conform the guidelines.
Comment #29
batigolix[removed duplicate comment]
Comment #30
larowlanLooks good to me.
Comment #31
webchickLooks great. Like the cross-linking to avoid repeating ourselves.
Committed and pushed to 8.x. Thanks!
Comment #31.0
webchickUpdate summary, which was out of date