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.
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
Comment | File | Size | Author |
---|---|---|---|
#28 | 2091367-field-help-28.patch | 36.94 KB | jhodgdon |
Comments
Comment #1
batigolixThis help text is way out of date and essential for many other help text because they (will) refer to this for further information.
Some of the to-do's:
- introduce entities (current text tries to avoid that term by describing them all)
- explain form display management
- change url()
Comment #2
jhodgdonProbably the intro to Entities should instead be a reference to the Entity module help, which should be explaining them?
Comment #3
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
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.
All of the specific field modules are now expecting something like this to be in the Field UI module help, so we'd better do something like this. :)
Comment #4
jhodgdonSo...
We now have a bunch of modules' hook_help() that is referring to this help page. They are expecting the following things to be described (and they should go into "Uses"):
- How to create and manage fields
- The Manage display page for each entity sub-type
- The Manage form page for each entity sub-type
For examples of how we are referring to these, see the Telephone module help (which is in Core now), and the Entity module help (which is in progress on this issue: #2091403: Create hook_help for Entity module). Also, we need to coordinate this with the Field module help -- the idea is that the Field module help will describe what fields are and refer to the Field UI help to describe how to manage them. That issue is #2091319: Update hook_help for Field module.
So I suggest that we have a short "About" section that basically says the module is for managing fields on entities and their display, and refers to the Field module help for an explanation of fields, and the Entity module help for an explanation of entities.
And then we'll need to make sure we have Uses bullet points for "Managing field display" and "Managing fields on forms", which I think are missing from the existing Field UI help. I think the help that is there about defining fields is probably fine -- it definitely seems comprehensive -- but it needs to be reviewed for accuracy in Drupal 8 (e.g., some of the names of pages and labels within pages might have changed).
Comment #5
ifrikI'm working on this.
Comment #6
robcarrShouldn't a lot of the text for the Field UI be removed... just a bit too long, not really helpful and wanders into the Field help text territory...
Also maybe there should be help on each of the tabs for managing fields, managing form, managing display (/admin/structure/types/manage/%/fields, /admin/structure/types/manage/%/form-display, /admin/structure/types/manage/%/display)?
Comment #7
ifrikHere's a first draft to re-do this.
I've mainly split the Uses into field settings, form display and display, plus knowing where to find out where all those fields are used.
The field settings are a bit complex because we have both the general field settings and the specific ones, and they are referred to in the same way.
Can somebody have a look at it to see whether that's a suitable way to go? Then I can finetune to wording afterwards.
Comment #8
jhodgdonHooray! I was hoping someone would write this sometime soon.
So, yes! I think this is a good approach. There are a few typos, which I didn't review carefully, since I think you are planning to fine tune. Two small typographical notes:
- When making lists like "a, b, or c" or "a, b, and c", we always want a comma after "b".
- Also I noticed an a herf tag instead of href. Near the end, in the "Listing" section.
Regarding the two types of settings... hm.... Yeah, the UI is bad. :( So, in the programming end of things, these are called "field settings" and "instance settings", and actually "instance settings" shows if you hover over the Edit link in the UI. So I think we can call them that in the help.
One other note... You cannot actually reuse fields across different entity types, only across sub-types or whatever we are calling them (for instance, fields you created for one content type can be used for another content type, but not for custom blocks or taxonomy terms).
I just checked the entity help and we describe them this way:
So we should be sure to use the same terminology in this help.
Thanks!
Comment #9
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 #10
mparker17Straight re-roll, therefore no interdiff.
Comment #11
mparker17Whoops, Issue Status.
Comment #12
mparker17Whoops, there was unresolved feedback... back to Needs Work. :P
Comment #13
er.pushpinderrana CreditAttribution: er.pushpinderrana commentedDid changes as mentioned in #9 and also fixed some broken links in this patch. And also attached the screenshot of Field UI help page.
Please review.
Comment #15
er.pushpinderrana CreditAttribution: er.pushpinderrana commentedFixed field help page URL.
Comment #16
jhodgdonThis text is still not accurate. You do not attach fields to an *entity*, you attach them to a sub-type. See comment #8 above.
Once we get the text being accurate, I will review the details more (typographical, grammar, etc.), but right now this is a major problem and the text needs to be rewritten completely.
Comment #17
rootworkI'm not thrilled with the term "entity sub-type" but since that's the wording we're using I went through and updated everything to match.
I added the Oxford comma where I noticed it lacking, and made various other typo cleanups. Several places used the verb "clicking" (as in a link), and I changed that to "using" since not everyone will be clicking -- if there's a better standard term for that, let me know.
There's a lot of "you can do x, and you can do y, and you can also do z" that makes it seem verbose. There's also a lot of "the settings include, for example, x, y, and z" because a lot of settings are dependent on what type of field it is. Additional work could be done to try to pare that down.
Comment #18
rootworkComment #19
jhodgdonLooking much much much better, thanks! A few things I think could be improved:
a) Let's capitalize the content type and vocabulary names in the About:
... such as article or page content types, or tag or category taxonomy terms. ...
==>
... such as Article or Page content types...
This also needs to be done elsewhere in the help where these content types are mentioned, such as in the field reuse section.
b) In "Creating a field":
"Entity sub-types include content types, taxonomy terms, and user profile accounts."
Hm.... Taxonomy terms are actually entity objects, the same way nodes are entity objects. The sub-type is the taxonomy *vocabulary*, the same way the content type is the sub-type for nodes. This also needs to be checked in the other sections of the page.
c) Next sentence:
" You can add new fields on the Manage fields page of an entity. "
No. It's on the entity sub-type, not the entity.
d) Same section:
" When you add a Label text, a machine name is automatically generated,"
Text is not countable, so you do not add "a text". Just take out the word "a", so it becomes "When you add Label text...".
d) The settings for a field are described twice: once in the Creating a field section, and then again in the Configuring section just below. This is redundant. Let's just do it once. Also, the information is confusing, because in Creating it says once you've created the field you cannot change the settings, and then in Configuring it says you can click Edit. Which is correct?
e) Configuring a field in a form section:
"On the Manage form display page of your entity,"
entity sub-type again! :)
f) Same section:
"allow you to configure the field further".
No, you are configuring the *widget* not the field. We need to be careful to be clear about this.
g) Same section:
"you can configure how each field is displayed on content creation pages"
I don't think I would say "displayed" here. I think I would say "edited".
h) In general... There is different usage of the word "field" throughout this help and it is very confusing. Sometimes it means "a field that is attached to an entity sub-type" and sometimes it means "a place to configure some kind of a setting for the field, widget, or formatter". I think we need to make this distinction clear.
So what I would propose is: In the About, we should add something like:
Note that throughout this topic, when referring to a Field in this sense, the word Field will be capitalized to distinguish from other uses of the same word.
Then we would make sure to capitalize the word "Field" when it refers to a Field module Field, and leave it lower-case for other uses. Either that or we should only use the word "field" to refer to a field-module Field and find another word for the other uses. ???
i) Widget section again:
"one or several widgets are available that allow you to configure the field further"
Um... maybe "one or several widgets are available, and most widgets have configuration options" ?
j) Display section:
"in a teaser or as a search result".
Do not use search result as an example here! That will confuse people a lot, because it doesn't really mean "Display this field as configured when you are building the search result page", it actually means "Render this field as specified, and use it to extract a snippet for the search result page". So I think it would be better to say "in a teaser or full page view" for the examples.
k) same section:
"one or several formats are available that allow you to configure the display of the field further"
As in Widget section, I think this would be clearer as "one or several formatters are available, and most formatters have configuration options". [Note: I also think we should call them "formatters" not "formats"]
l) same section:
"You exclude a field from a specific display, by choosing..."
I think the word "can" is missing?
m) Reusing section:
"(If no fields are available that could be re-used, this list is not displayed.) "
Verb tense: could => can
n) Listing section:
"all fields are listed with name, type and linked to the entity sub-type with which they are used"
Um. This seems a bit awkward grammatically... How about:
each field is listed with its label, field type, and a link to the entity sub-types where it is used
...actually, we should check what happens in this list if you reuse a field. Do you get one entry or multiple?
Anyway... This is all fairly minor except we need to figure out what to do about (h). Looking really good!
Comment #20
batigolixComment #21
batigolixThis issue #2041819: Update hook_help and menu entries for Entity module to describe display modes contains a patch that tries to change the field_ui module hook_help.
I proposed to close that issue and continue the work here.
Comment #22
batigolixThese are the changes we would like to include in field_ui hook_help (coming from : #2041819: Update hook_help and menu entries for Entity module to describe display modes):
a) add a section that explains entities:
b) add how to use display modes:
c) add description to field ui pages:
Comment #23
jhodgdonInstead of having one critical parent issue I have been asked to change the status of each child issue.
This issue is Major. We are missing some very important help.
Comment #24
jhodgdonPhew! I decided it was time to move this issue towards completion.
So I did the following:
a) Rewrote most of the Field module help, including the terminology about entities and fields that was previously in the Entity help (there is no more entity module). I decided the best thing to do was to add a Terminology section after About. I think we did that on at least one other help page but I have no idea which one. Anyway, it seemed like a good idea, because it wasn't an "About this module" or a "Uses" but we needed the information. I also added formatters to the list of modules; not sure why they were not included before.
b) Throughout other core module help, replaced links that had gone to the Entity module help with links to the new Field module help (these were links like "For background on entities, see the Entity module help page", and this info is now on the Field help page). I think I found all the links.
c) Rewrote the Field UI module help, and reorganized the Uses section. I think it's pretty clear and pretty compact now, but presents all the necessary information. I added sections on how to manage view modes and form modes, which had been in the Entity help previously (it is now part of Field UI module).
So... Help pages that should be looked at to make sure they're OK with this patch:
Field
Field UI
Comment
Content Translation
Entity Reference
Responsive Image
RESTful Web Services
User
Given that I changed I am pretty sure every line in the previous patch, I have not made an interdiff file.
Comment #25
jhodgdon#2332687: Lost help for field types from Core/Field is now postponed on this issue. Can someone please review the help?
Comment #28
jhodgdonReroll.
Comment #29
ifrikThe detailed list of terminology in the Field module help is great.
I checked the eight help texts and their references to fields, and it looks fine. All the links work.
Comment #30
Sivaji_Ganesh_Jojodae CreditAttribution: Sivaji_Ganesh_Jojodae commentedComment #31
ifrikComment #32
webchickCommitted and pushed to 8.0.x. Thanks!