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

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

jhodgdon’s picture

There 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. :)

jhodgdon’s picture

Although... 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.

cyberdog’s picture

Assigned: Unassigned » cyberdog
andrewmacpherson’s picture

Assigned: cyberdog » Unassigned

This 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.

andrewmacpherson’s picture

Issue tags: +d8help

adding tags, updated issue summary

cyberdog’s picture

Basic correction of listed core field sub-modules, Modules > Extend

cyberdog’s picture

Status: Active » Needs review
lostkangaroo’s picture

Looks like links were not upgraded to the latest and greatest checkout https://drupal.org/node/632280 for more information on this.

mr.baileys’s picture

Note 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..

jhodgdon’s picture

Status: Needs review » Needs work

The 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).

jhodgdon’s picture

Issue summary: View changes

Updated summary to include related issues; added enabled-modules-list task

ifrik’s picture

The 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.

raedkhurayji’s picture

Issue summary: View changes

I 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 ).

jhodgdon’s picture

Thanks 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.

jhodgdon’s picture

We 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.

amitgoyal’s picture

Status: Needs work » Needs review
FileSize
4.8 KB
6.89 KB

@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.

jhodgdon’s picture

Status: Needs review » Needs work

Wow, 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:

... Drupal core includes the following field type modules: <a href="!text-help">Text</a> (required), 

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.

amitgoyal’s picture

Status: Needs work » Needs review
FileSize
3.54 KB
4.71 KB

Thanks 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.

jhodgdon’s picture

Issue summary: View changes
Status: Needs review » Needs work
Issue tags: +Novice, +Needs manual testing

Great!

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...

amitgoyal’s picture

All links to drupal.org have been updated to https.

amitgoyal’s picture

I have also did the quick manual test and everything (links, UI, formatting) looks good to me.

mparker17’s picture

Issue summary: View changes

Whoops, issue summary looks like it was copied from one about Content Translation ;)

mparker17’s picture

Status: Needs review » Reviewed & tested by the community

Code looks good.

Manual testing shows all the links work and the terminology appears to be consistent with the rest of the help pages.

jhodgdon’s picture

Status: Reviewed & tested by the community » Fixed

Thanks again everyone! Committed to 8.x.

  • Commit 4abcd06 on 8.x by jhodgdon:
    Issue #2091319 by amitgoyal, mparker17, cyberdog: Update hook_help for...

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.