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 |
---|---|---|---|
#19 | 2091403-19-entity_help.patch | 4.03 KB | jhodgdon |
#19 | interdiff.txt | 6.28 KB | jhodgdon |
#18 | help_entity.png | 76.89 KB | StuartJNCC |
#16 | 2091403-16-entity_help.patch | 4.02 KB | jhodgdon |
#16 | interdiff.txt | 6.11 KB | jhodgdon |
Comments
Comment #1
batigolixThis seems to me to be the most crucial help text that needs to be written, because it will be referred to by many other help text.
If well explained we can use the entity concept througout the rest of the drupal help without having to worry
Luckily there is decent on line docs on this subject available that we can extract from: https://drupal.org/node/1261744
Comment #2
jhodgdonYes, we need a good explanation of what entities are to go in this module, so that the Field and Field UI modules can link here.
Discussion of what to say has been going on:
#2030569: [policy] Decide how to refer to "entities" and "bundles" in D8 UI
See comment #23 especially.
Comment #3
Sree CreditAttribution: Sree commentedSo, the help doc would have the text mentioned in #23 of above mentioned issue or would it be updated further?
This help doc covers about display modes & few other such concepts as well?
Comment #4
jhodgdonI think that the Entity module help needs to:
- explain what the entity module itself does (which is basically set up the framework for entity type modules, and handle display modes and form display modes)
- explain what Entities are and give some examples
- refer to the Field module and Field UI module help for information about fields
- explain what display modes and form display modes are.
- explain how to set up display modes and form display modes. (that should go in Uses; I think the rest belongs in About probably).
Also, this module has *no* help now, which makes this task actually "critical" level. Updates to help are not critical, but completely missing help is a violation of the documentation gate.
Also, issue status is "active" until there is a patch.
Comment #5
batigolixI actually started with this some weeks ago, but I got a little delay.
Below you find a first draft that re-uses info from several sources such as:
- https://drupal.org/node/1261744
- #2030569: [policy] Decide how to refer to "entities" and "bundles" in D8 UI
- http://www.youtube.com/watch?v=coephBu07Ks
The draft is a bit long and I'm thinking that it might be better to put this on drupal.org and have a compressed version as hook help text instead.
I did no proof reading, mark upping or spell checking so please look at the general structure and concepts only.
Comment #6
jhodgdonWe do not want to use the word "bundles" in the help text. This is not used anywhere in the user interface, and will be confusing to end users, which is who the help is aimed at. We also want to avoid using other technical terms, such as "controller". This is help for a site administrator.
So... this is a good start, but I think it needs to be rewritten with that in mind. Also, I don't think it needs to go into that much detail. I think the first two paragraphs in About are sufficient, and the rest can be omitted. Just add a short explanation of View Modes in the Uses section about them.
Thanks!
Comment #7
BerdirNote that the entity.module *only* provides the form/view modes (for technical, CMI related reasons, we want to change this) and their UI.
Everything else is part of the Core\Entity *system*.
So, on one side, I'm not sure that explaining the entity system really belongs in a hook_help(), that's like block_help() describing @Block plugins, or field_help() describing how field types work. They just state that they exist and how to use them.
On the other side, we should explain the common terms around entities that are relevant for users and this might be an as good place as any other.
There are long discussions in multiple issues if "Entity" should be exposed to users, but I really don't think that we have a choice. We *need* a term to group all these things together, and e.g. use it for Entity reference.
Comment #8
jhodgdonWe definitely need to use the word "entity" (we don't have a better term that encompasses everything entities are), and we definitely need a central place that explains this term *briefly*. Because we have been unable to come up with a better help system for Drupal Core, we are stuck with hook_help(), and therefore with help being tied to modules. So we can either add this help to the System module or to the Entity module, and I think it makes the most sense to add it to Entity myself.
Comment #9
BerdirYes, agreed :)
I just meant that we shouldn't document the *API* or how it works internally (controllers, storing API, ..) in hook_help(), just what an Entity is.
Also, there are config and content entities, which are quite different, not sure if and how that should be mentioned.
Comment #10
jhodgdonOh definitely! This is help for site admins, not programmers.
It does seem like in our explanation of what an entity is, we might mention content entities and configuration entities, and give examples of each... but only if an average site admin will encounter config entities and do things with them... and I think they generally don't, right? Hmmm ... using the text in #5 as a starting point, how about something like this?
Comment #11
BerdirOh, they most certainly do. It might not be as obvious as content entities, but they are everywhere.. from node types, over views, to text formats...
Comment #12
jhodgdonTrue, regarding config entities. What do you think about the way the patch in #10 describes them though? I am just not sure that the average site admin needs to even know that config entities exist, or that their node types are managed via config entities?
Comment #13
jhodgdonI talked briefly with Berdir in IRC just now about config entities, and have expanded this help a bit.
Comment #14
batigolixIn the following t() the definition of link tokens !field and !field_ui are missing:
I find the mixed usage of content entity, basic content entity, content entity type and basic content entity type confusing.
I feel the word complex in Configuration entity types are used to store complex configuration is not necessary.
Comment #15
jhodgdonI'm not sure what to do about the terminology.
"content entity type" refers to any entity type that is content-related: nodes, comments, etc. We don't want to use the word "node" since that was taken out of the UI in D7. So what would you call "nodes", to differentiate them from other entity types that are also content-related, without using the word "node"?
And the word "complex" is actually necessary, IMO. Simple configuration is not stored in entities. Complex configuration is.
Comment #16
jhodgdonI guess in the Node module, we refer to it as the "main site content". Here's a new patch.
Comment #18
StuartJNCC CreditAttribution: StuartJNCC commentedHere is a screen shot of the what the help looks like with the patch in #16 applied (with the missing closing bracket fixed!:
Like batigolix in #14, I don't much like:
I think my problem is that is does not give me a concrete example of what a sub-type is in either of the situations described. How about:
Some entity types can have sub-types (for example articles or basic pages within the main site content entity type, and tags within the taxonomy term entity type)
Could we also lose a repetition of "entity sub-type" in the penultimate sentence of the managing views and managing forms sections:
Once a view mode has been set up, you can choose and format fields for the view mode within each entity sub-type on the Manage display page for that sub-type.
Once a form mode has been set up, you can choose which fields are available on that form within each entity sub-type on the Manage form display page for that sub-type.
Comment #19
jhodgdonThanks! I agree with #18. Here's a new patch and an interdiff.
Comment #20
eporama CreditAttribution: eporama commentedThis text reads really cleanly now for me. Originally, I wondered if there was a need for an item in the Uses list for "configuration entities" since we have two uses for "content entities". However there doesn't appear to be a lot that you can manipulate in the UI for configuration entities, so I think it reads well as is.
Comment #21
webchickAwesome!! This is going to be a huge help to people understanding what the heck is going on here.
Committed and pushed to 8.x. Thanks! Great work, folks.