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

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

batigolix’s picture

Priority: Normal » Major
Status: Active » Needs work

This 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

jhodgdon’s picture

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

Sree’s picture

So, 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?

jhodgdon’s picture

Priority: Major » Critical
Status: Needs work » Active

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

batigolix’s picture

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

About

The Entity module provides the basic building blocks for the website by allowing the definition and management of entity types.

Entities are abstractions of website content such as comments, taxonomy terms, users and nodes. Entity types can have sub types (called "bundles") to which fields can be attached.

Entity types

In a standard Drupal website a number of entity types is predefined, among which:
Nodes
Comments
Custom blocks
Taxonomy terms
Files
Menu links

Through the Entity module other entity types can be defined such as shopping baskets, payments or user groups.

The Entity module provides a controller for creating, reading, updating and deleting
entity types.

View modes and form modes

The Entity module allows users to manage view modes and form modes for entities.

By creating and editing view modes, such as "full content" or "teaser", you define how entities are displayed in the website. In a standard Drupal website the following view modes are defined for the Node entity type:
Full content
Teaser
RSS
Search result
Search index
For each of these view modes you can define which fields are shown and how each of these fields are presented to the visitor.

By creating and editing form modes you define the appearance of the entry forms such as the user registration form.

Bundles

Bundles are sub types of entity types to which fields can be added.

In a standard Drupal website the following bundles are defined for the Node entity type:
Basic Page
Article
Each content type that you create via the Content type
management interface
becomes a bundle of the Node entity type.

Each vocabulary that you create via the Taxonomy management interface becomes a bundle of the Taxonomy term entity type.

Some entity types like "user" only have a single bundle.

Find out more about fields in the field help text

Uses

Managing view modes
You can create, edit the name and delete view modes for all entity types from the View modes page. All view modes are available in the Manage display page of an entity type. Find out more about managing displays in the Field UI help text

Managing form modes
You can create, edit the name and delete form modes for all entity types from the Form modes page. All form modes are available in the Manage form display page of an entity type. Find out more about managing form displays in the Field UI help text

jhodgdon’s picture

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

Berdir’s picture

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

jhodgdon’s picture

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

Berdir’s picture

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

jhodgdon’s picture

Status: Active » Needs review
FileSize
3.56 KB

Oh 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?

Berdir’s picture

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?

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

jhodgdon’s picture

True, 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?

jhodgdon’s picture

I talked briefly with Berdir in IRC just now about config entities, and have expanded this help a bit.

batigolix’s picture

Status: Needs review » Needs work

In the following t() the definition of link tokens !field and !field_ui are missing:

$output .= '<p>' . t('Content entity types store most of their text, file, and other information in fields. See the <a href="!field">Field module help</a> and the <a href="!field_ui">Field UI help</a> pages for general information on fields and how to create and manage them.') . '</p>';

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.

jhodgdon’s picture

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

jhodgdon’s picture

Status: Needs work » Needs review
FileSize
6.11 KB
4.02 KB

I guess in the Node module, we refer to it as the "main site content". Here's a new patch.

Status: Needs review » Needs work

The last submitted patch, 2091403-16-entity_help.patch, failed testing.

StuartJNCC’s picture

FileSize
76.89 KB

Here is a screen shot of the what the help looks like with the patch in #16 applied (with the missing closing bracket fixed!:

entity help

Like batigolix in #14, I don't much like:

Some entity types are further grouped into sub-types (such as content types within the main site content entity type, and vocabularies within the taxonomy term entity type)

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.

jhodgdon’s picture

Status: Needs work » Needs review
FileSize
6.28 KB
4.03 KB

Thanks! I agree with #18. Here's a new patch and an interdiff.

eporama’s picture

Issue summary: View changes
Status: Needs review » Reviewed & tested by the community

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

webchick’s picture

Status: Reviewed & tested by the community » Fixed

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

Status: Fixed » Closed (fixed)

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