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.Problem/Motivation
This is a follow-up from #2862458: [META] Once media is enabled, having the File, Image and Media reference fields all listed is confusing.
On that issue, we allowed plugin descriptions defined in field type annotations to be shown on the UI.
We need to make sure that all descriptions currently present in the annotations make sense for the "average site builder", once they are now going to be exposed through the UI.
The following table indicates the current field descriptions from the annotations, and the proposed new texts:
| Field | Current Description | Proposed Description |
|---|---|---|
| boolean | An entity field containing a boolean value. | Use a 'Boolean' field for a value with two options: 'On' or 'Off', True or False, 1 or 0. |
| comment | This field manages configuration and presentation of comments on an entity. | Use a 'Comments' field to enable comments. You will be able to configure comments in the field configuration. |
| datetime | Create and store date values. | Use a 'Date' field for a date or a date and time. |
| An entity field containing an email value. | Use an 'Email' field for an email address. | |
| timestamp | An entity field containing a UNIX timestamp value. | Use a 'Timestamp' field for a date and time stored as a UNIX timestamp. |
| link | Stores a URL string, optional varchar link text, and optional blob of attributes to assemble a link. | Use a 'Link' field for a URL. It can also store the link text. |
| list_float | This field stores float values from a list of allowed 'value => label' pairs, i.e. 'Fraction': 0 => 0, .25 => 1/4, .75 => 3/4, 1 => 1. | Use a 'List (float)' field for float values from a fixed list of 'value => label' pairs. For example, the Fraction field could allow 0 => '0', .25 => '1/4', .75 => '3/4', 1 => '1'. |
| list_integer | This field stores integer values from a list of allowed 'value => label' pairs, i.e. 'Lifetime in days': 1 => 1 day, 7 => 1 week, 31 => 1 month. | Use a 'List (integer)' field for integer values from a fixed list of 'value => label' pairs. For example, the Lifetime field could allow 1 => '1 day', 7 => '1 week', 31 => '1 month'. |
| decimal | This field stores a number in the database in a fixed decimal format. | Use a 'Number (decimal)' field for a number with a fixed number of decimal digits. |
| float | This field stores a number in the database in a floating point format. | Use a 'Number (float)' field for a floating-point number. |
| integer | This field stores a number in the database as an integer. | Use a 'Number (integer)' field for an integer. |
| field_ui:entity_reference:node | An entity field containing an entity reference. | Use a 'Content' field for a reference to related content (or node). |
| entity_reference | An entity field containing an entity reference. | Use a generic 'Reference' field for references to other entities. This includes content entities, such as comments and custom blocks, as well as configuration entitites, such as date formats and views. |
| file | N/A (modified in #2862458) | Use a 'File' reference when you want to upload an arbitrary file to an entity, generally without re-usability needs. If in doubt, 'Media' references should be preferred instead. (after #2862458) |
| image | N/A (modified in #2862458) | Use an 'Image' reference when you want to upload an image to on entity, generally without re-usability needs. If in doubt, 'Media' references should be preferred instead. (after #2862458) |
| field_ui:entity_reference:media | N/A (modified in #2862458) | Use a "Media" field to reference assets such as files, images, videos and more. You will be able to select which media types can be referenced in the next steps. (after #2862458) |
| field_ui:entity_reference:taxonomy_term | An entity field containing an entity reference. | Use a 'Taxonomy term' field to reference a term from one or more vocabulary. |
| field_ui:entity_reference:user | An entity field containing an entity reference. | Use a 'User' field to reference a Drupal user account. |
| list_string | This field stores text values from a list of allowed 'value => label' pairs, i.e. 'US States': IL => Illinois, IA => Iowa, IN => Indiana. | Use a 'List (text)' field for a string value from a fixed list of 'value => label' pairs. For example, the 'US State' field could allow 'IL' => 'Illinois', 'IA' => 'Iowa', 'IN' => 'Indiana'. |
| text | This field stores a text with a text format. | Use a 'Text (formatted)' field to store short text that allows rich-text formatting (HTML). |
| text_long | This field stores a long text with a text format. | Use a 'Text (formatted, long)' field to store long text that allows rich-text formatting (HTML). |
| text_with_summary | This field stores long text with a format and an optional summary. | Use a 'Text (formatted, long, with summary)' field to store long text, and an optional summary, that allow rich-text formatting (HTML). This is used for the Body field of the standard Article and Page content types. |
| string | A field containing a plain string value. | Use a 'Text (plain)' field for short, unformatted text. You must configure the maximum length for this field. |
| string_long | A field containing a long string value. | Use a 'Text (plain, long)' field for long, unformatted text. |
Proposed resolution
Review the wording of all existing descriptions to make sure they are understandable by the site builder.
Comments
Comment #2
marcoscanoPostponed on #2862458: [META] Once media is enabled, having the File, Image and Media reference fields all listed is confusing.
Comment #3
marcoscanoAs pointed out in #2862458-74: [META] Once media is enabled, having the File, Image and Media reference fields all listed is confusing, there's nothing preventing us from advancing the discussion about the texts here, to have them ready and just waiting the right time to be committed.
Once the implementation of this is less important than the texts themselves, I suggest we try to reach consensus on the strings, and then write a patch with them.
Even if I'm probably not the most qualified for it :), here's a first shot aiming to improve what we currently have:
etc.
Use this field when you want to relate two nodes together. For example, in a "Related articles" context.
It's hard not to get into technical details for some of them, because strictly speaking, the user is choosing the storage of the field on this screen, so even if not very explicit, they are making a technical decision in the end.
This makes me wonder if we shouldn't further improve this same screen (once there's so much white space... :) with something that would explain how fields in Drupal are created/configured? Something like
but I guess this is probably material for another different issue...
Comment #4
BerdirRandom thoughts, I suggest you wait for more feedback before doing anything:
* boolean: not sure if we need mutliple examples or even "e.g.", maybe one is enough to keep it simpler?
* comment: while technically we only store settings in the comment field, for the user, it actually enables having comments, so it should probably have more focus on that.
* datetime: Possibly explicitly mention "date and time (optional)" or so?
* timestamp: "Stores a date field" <-- no "field", we just store a date, not a "date field" :)
* link: stuff about blob is too technical. Maybe leave out attributes completely because core does not actually provide a widget to manage link attributes? Also no need for "varchar title", just title is enough.
* decimal (and others): No need for "in the database" and similar things. Might not actually be correct (contact forms don't store anywhere by default), not relevant and all fields store something in the database if the entity is saved.
* entity_reference: a field with multiple values connects more than just two entities together, maybe just References another entity or something like that, without explicit "two".
* entity reference:*: IMHO I wouldn't talk about an ID there, just a reference, it doesn't matter to the user how it is explicitly stored internally?
* string_long: string_long can be *really* long, so I wouldn't mention an explicit limit. There is also no UI in core to configure a limit.
Help text: yeah, I'd suggest different issue and I know that the UX team wants to revamp the whole thing, so wouldn't invest too much time there. On the other side, those ideas/plans have existed for years and we haven't seen much yet (in core).
Comment #5
BerdirI would also suggest to keep the list of suggestions (only) in the summary, then everyone can edit it and we can update it, maybe just mention changes then in the comment.
Comment #6
marcoscanoThat makes sense, thanks!
I've moved the table proposed in #3 to the IS, so next tweaks can be followed by checking the diffs.
Comment #7
marcoscanoAnd now I've included as well some of the feedback from #4.
Thanks!
Comment #8
yoroy CreditAttribution: yoroy at Roy Scholten for Dropsolid commentedThanks for listing all the strings @marcoscano.
As I started reviewing and rewriting, I noticed we need to make an explicit decision about the perspective from which these strings are written:
Should we describe the item’s behaviour or describe the user goal/result? Examples:
“Stores a number as an integer” or “Store integer numbers”
“Stores a date value in the format of a UNIX timestamp” or “Store dates as UNIX timestamps”. We use the former pattern on the modules page so we could choose to be consistent with that. I personally don't really like it because it reads more like passive documentation where the latter subtly guides me along, talks to me about what I want to achieve.
Also:
- I think we can do without the "in the format of" bits that are used here and there
- For the references: do we want to be explicit about "one or more" things you can reference?
- This was already the case but: In the list_* descriptions I’m confused about how the single quotes are used in the first general pattern example vs. the examples that follow. The quotes are around the full pattern initially, then in the examples only around the initial label?
Ran out of time to update the strings in the issue summary table so excuse the quick dump here. I'm still mixing perspectives here, so use this to get a feel for how both approaches differ and then lets choose one:
Stores boolean values, such as "On/Off".
Add this field to allow comments on the entity.
Store date and time values.
Store a valid email address.
Store a date as a UNIX timestamp.
Stores a URL string with an optional link text to create a link.
.
.
Store a number in a fixed decimal format.
Stores a number in a floating point format.
Stores a number as an integer.
Stores a reference to a content item. Use this field when you want to relate content. For example, in a "Related articles" context.
A generic entity reference field to relate entities together.
.
.
.
References a taxonomy term related to the entity this field is attached to.
Creates a reference to a user.
Stores text values from a list of allowed 'value => label' pairs, i.e. 'US States': IL => Illinois, IA => Iowa, IN => Indiana.
Stores a text that allows rich-text formatting (HTML).
Stores a long text that allows rich-text formatting (HTML).
Stores a long text that allows rich-text formatting (HTML). It also provided a "Summary" field to store a shorter version of the text.
Store a plain text string of max XX chars.
Store a long plain text string.
Comment #9
benjifisherMy initial thought was that getting rid of the "in the database" phrase was a step in the right direction, and that we should go for short phrases describing the values, cutting out the repetitive "stores" and "values".
Then I looked at the three descriptions in #2862458: [META] Once media is enabled, having the File, Image and Media reference fields all listed is confusing. (These are not listed in the issue description nor comments there, except for screenshots, so I extracted them from the patch.) Since those have already been discussed a bit, I decided to use them as a model: "Use a 'Foo' field to ...". I also include them in the issue description.
This goes against my initial thought to cut down on repeated phrases. On the other hand, I think it is much worse to call the field type one thing in the "Add a new field" select list and then call it something else in the description. Imagine the confusion if you select "Text (short)" from the select list, and the description refers to "string". Yes, that's what I want, but I do not see "string" as an option!
I am replacing the table in the issue description with my own version. I have not made any changes based on @yoroy's comment above. I think I address at least one of the points there, being more consistent about using quote in the
list_*field types.P.S. I am not happy with my description of the
decimalfield: "Use a 'Number (decimal)' field for a number with a fixed number of decimal digits." Can we avoid using the word "number" twice?Comment #10
joachim CreditAttribution: joachim commented> Since those have already been discussed a bit, I decided to use them as a model: "Use a 'Foo' field to ...". I also include them in the issue description.
The problem with starting all the field description texts with 'Use a...' is that they then only make sense when creating a field. You can't, for example, display them somewhere on an existing field.
Comment #11
marcoscanoUp until now these descriptions weren't being used anywhere, so an argument could be made that a need to display them somewhere else is quite remote. IMHO, it would be preferable to have a good description that works well for this page, and when (and if) the need appears to show them somewhere else, we can decide how to deal with that. I think this would be better than trying to find a generic-enough description that could work everywhere, but with limited (or not as good) result on this page.
Comment #12
phenaproximaComment #13
joachim CreditAttribution: joachim commented> IMHO, it would be preferable to have a good description that works well for this page, and when (and if) the need appears to show them somewhere else, we can decide how to deal with that.
If this were just in core, then sure, that would be a viable plan.
But what we do here sets the pattern for all field type plugins, in core and contrib. If we write them in this format, then contrib will follow suit. If then later on in the D8 cycle we find we want to show the descriptions in another context, we won't be able to.
Comment #14
benjifisher@joachim, I think the right place for this discussion is the parent issue, #2862458: [META] Once media is enabled, having the File, Image and Media reference fields all listed is confusing. I will reply to your comment there.
Comment #15
ifrikThanks for putting all of these together in a list, and I agree with Roy that this is a decision about the question that we assume most users will have in their head. One is "What does this field do? Does it what I want?", the other is "Which of these fields do I choose to do xyz?"
Looking at both lists of proposed wording: Many of the them don't really give more information then the field label itself (for example, Email), but some give a bit more information. But some give additional information (for example that a comment field can be configured further, or that a boolean field can be used with different wording.) and this is more useful for the people that look it at it and wonder which one to choose. Also it's more the newer users who will be reading these texts, while at a later stage we don't need to look at the descriptions any more.
So I would go for the "Use for..." and "Use when...." descriptions, and I would even add a bit more to it then there is now where there is more option available then users might assume.
For example:
An additional note: Formatted text is not necessarily "rich-text formatting (HTML)". Depending on the text editor used, it can be other types of formatting as well. This got discussed at length while writing the help text for the Editor module, so you can take some wording from there (/admin/help/editor)
And for list strings: Can we have a different example instead of US states? There's already enough US references build into Drupal :-) Maybe whole countries? AUS : Australia, AR | Argentina maybe?