Early Bird Registration for DrupalCon Portland 2024 is open! Register by 23:59 PST on 31 March 2024, to get $100 off your ticket.
Background
This issue is part of the task to update the hook_help texts of the Drupal 8 modules:
#1908570: [meta] Update or create hook_help() texts for D8 core modules
Tasks
- Review / write the hook_help text according to help guidelines
- Refactor the enabled field modules list, using annotation-based discovery. [out of scope for this issue]
- (novice) Final manual testing:
1. Apply the patch.
2. Go to admin/help.
3. Click on the help page for this module (Field).
4. Verify that the help page is OK:
- Verify that all the links work
- Verify that all mentions of pages/text/permissions within the UI match what is seen in the UI
- Verify that the formatting is OK.
Related Issues
Comment | File | Size | Author |
---|---|---|---|
#19 | interdiff-2091319-17-19.txt | 3.45 KB | amitgoyal |
#19 | field-update-hook_help-2091319-19.patch | 3.54 KB | amitgoyal |
Comments
Comment #1
jhodgdonThere is a suggestion for what to put in this help text on
#2030569-23: [policy] Decide how to refer to "entities" and "bundles" in D8 UI
All of the specific field modules are now expecting something like this to be in the Field module help, so we'd better do something like this. :)
Comment #2
jhodgdonAlthough... this suggestion is a bit out of date, since we now want to put an introduction to entities in the Entity module instead and link there.
Comment #3
cyberdog CreditAttribution: cyberdog commentedComment #4
andrewmacpherson CreditAttribution: andrewmacpherson commentedThis field_help() has some logic to display a list of enabled field modules. Currently it looks for hook_field_info implementations, but these are being removed as part of #2014671: [META] Convert all field types to plugins.
If we want to keep this list of related modules, we'll need to refactor this to use annotation-based discovery.
Comment #5
andrewmacpherson CreditAttribution: andrewmacpherson commentedadding tags, updated issue summary
Comment #6
cyberdog CreditAttribution: cyberdog commentedBasic correction of listed core field sub-modules, Modules > Extend
Comment #7
cyberdog CreditAttribution: cyberdog commentedComment #8
lostkangaroo CreditAttribution: lostkangaroo commentedLooks like links were not upgraded to the latest and greatest checkout https://drupal.org/node/632280 for more information on this.
Comment #9
mr.baileysNote that the hook_field_info() to Plugin refactoring mentioned by @andrewmacpherson ni #4 is handled in #2099261: field_help() no longer lists field_type/widget modules and can throw undefined index notice..
Comment #10
jhodgdonThe help for this module needs some more editing beyond the latest patch above.
This help is becoming more necessary -- we are now or will be soon referring to this module from the Entity help (#2091403: Create hook_help for Entity module), the Field UI help (#2091321: Update hook_help for Field and Field UI module), and all the individual field module help (listed on #1908570: [meta] Update or create hook_help() texts for D8 core modules). All of these are expecting this module to describe what fields are... but I think the existing About text is doing a pretty good job of it now.
Anyway, some things that need to be updated:
a) We should link to the Entity module help for more information about entities, right in or after the first sentence of About where it says that fields can be defined for entity types.
b) As noted above, we need to change the formatting of links within the text. The guidelines are at
https://drupal.org/node/632280#url-note
c) I don't think we should try and list all of the existing core field modules, as is done (or attempted, or at least implied) in the Enabling field types "Uses" bullet point. This list is hard to maintain, and is bound to get outdated. How about just saying something like:
Core includes field modules for many types of data, such as the general-purpose Text and File field modules, and the narrower-purpose Email, Telephone, and Image modules. In addition, there are several modules that provide input widgets for other field modules, such as the Options module.
(and each of these should be links to the respective help for the module).
Comment #10.0
jhodgdonUpdated summary to include related issues; added enabled-modules-list task
Comment #11
ifrikThe patch doesn't apply anymore.
error: patch failed: core/modules/field/field.module:119
But since it needs rework anyway, I take the previous work and the comments up together.
Comment #12
raedkhurayjiI was working on #2090525: Update hook_help for menu module and found out under the (admin/help/field) under Uses paragraph, one of the list doesn't not have link for the ( Datetime ).
Comment #13
jhodgdonThanks for pointing that out! I see that too. On admin/help/field, the Datetime field is included in the list of fields, but it isn't a link.
However, the reason is not actually a bug in the Field module -- the reason is that the Datetime module currently does not have a help page, so there is nothing to link to. That is a separate issue:
#2091397: Create hook_help for Datetime module
So, we do not have to worry about that right now. The Field module is working correctly -- displaying all the available fields, and making them links to the module help page if the module has a help page defined.
Comment #14
jhodgdonWe just had a change to hook_help, on this issue: #2183113: Update hook_help signature to use route_name instead of path.
Here is the change record: https://drupal.org/node/2250345
This patch will need a reroll for this change.
Comment #15
amitgoyal CreditAttribution: amitgoyal commented@jhodgdon - Please review attached patch which will fix the issues mentioned in #10 and #11.
Regarding 'c) I don't think we should try and list all of the existing core field modules' under #10,
This module list is generated dynamically by the code based on the enabled modules. And it will also link to their respective help pages if the hook_help() is implemented in the module. So we don't need to worry about maintaining this list as such.
Comment #16
jhodgdonWow, thanks for reviving this issue, which had not had a patch since September!
Some things to fix:
a) In About, the link to the online documentation is not following our current help guildelines/standards.
b) In the Uses about Enabling field modules:
We should not be listing these modules here, as discussed above -- send people to the Extend page to find a list of available modules, and refer to the generated list of enabled field modules that will appear automatically below. Maybe mentioning Options makes sense, but I think not if it appears in the generated list.
Comment #17
amitgoyal CreditAttribution: amitgoyal commentedThanks for your feedback @jhodgdon.
a) I have updated the link to the online documentation.
b) I have removed the listing of modules in Enabling field section as these are appearing automatically by the code.
Please review.
Comment #18
jhodgdonGreat!
Just one more very minor thing: All links to drupal.org should now go to https not http.
Then this patch needs a quick manual test:
- Verify that all the links work
- Verify that all mentions of pages/text/permissions within the UI match what is seen in the UI
- Verify that the formatting is OK.
Setting tags for that...
Comment #19
amitgoyal CreditAttribution: amitgoyal commentedAll links to drupal.org have been updated to https.
Comment #20
amitgoyal CreditAttribution: amitgoyal commentedI have also did the quick manual test and everything (links, UI, formatting) looks good to me.
Comment #21
mparker17Whoops, issue summary looks like it was copied from one about Content Translation ;)
Comment #22
mparker17Code looks good.
Manual testing shows all the links work and the terminology appears to be consistent with the rest of the help pages.
Comment #23
jhodgdonThanks again everyone! Committed to 8.x.