Create tokens for entity labels

Moving to the token system component, to get it on the radar of token maintainers. How should we handle entity-generic tokens in general? E.g. tokens for entity labels but also entity urls and possible others?

I think it somehow makes sense to have both, the node title and the node label available. As once a module changes the label to point to something else, the title token should still give on the title. Maybe just the overall "node" token without property should point to the label?

For now we should handle them individually in each module's token integration. I'm not sold on using the term 'label' in public facing text. Will users really understand that terminology when we never expose the world 'label' in the UI? I think we should still use the terms we use in the UI, but make 'raw' versions available. So something like [node:title-raw] 'The raw title of the node.' with [node:title] 'The title of the node.'.

Can someone explain how this relates to #1764358: Core token values do not use the new entity methods and #2164635: Automatically expose typed data to token API?

Since those issues were created after this issue, I'm not sure? Although I'm guessing that #1764358: Core token values do not use the new entity methods should supersede this issue.

Reorlled.

Re-rolled against 9.1.x-dev .

Needs patch (or MR) against 9.3.x

Updated patch from #17. Tried to fix the custom errors, please review.

This is a great example of a simple patch with far-reaching consequences, especially since it introduces new usable tokens to the UI.

This task was created as a space to discuss potential changes to these tokens.

@gaspaio enumerated the possible ways forward in this comment:

We can :
1) leave the old tokens and do not create new ones for $term->label() and $node->label().
2) leave the old tokens and create new ones for $term->label() and $node->label().
3) keep the old token names but replace their value with $term->label() and $node->label().

And I note with interest this comment from @Berdir:

There was never such a thing as an "entity title", only "node title". Label is a more generic term and the entity_label() function already existed in 7.x. This does not introduce any new concepts, it just consistently uses one that already exists for quite a long time now.

An entity label can be a node title, a comment subject, a user name, ...

In my opinion, while standardising to use 'label' within the code makes sense where that code might be extended and used in other ways, but these tokens are specific to Node and Token and already use the correct specific labels for those entities, which is a better user experience for the primary users of tokens: site builders.

I think there's a case to make for using ->label() under the hood (option 3) however I have seen a comment or two expressing concern that this may lead to a breakage if the definition of label is ever changed. I'm not convinced this is a concern but I'm very willing to learn how it might be.

If it is decied that this is a good change to make there are a bunch of things that need to happen to support it:

1. The new tokens need tests.
   
2. A change record is needed, indicating what's happening and why.
   
3. If we use option 2 from @gaspaio's summary, I think the existing tokens that perform the same function need to be deprecated. At minimum a description should be added to node:title and term:name to indicate that they have been replaced by the new 'label' versions, else why change them at all? That description should link (or at least provide the URL) to the change record.

I wouldn't put effort into those until a decision has been reached, so I've set this to Active rather than Needs Work for now.

I agree that using $entity->label() under the hood makes sense. We have a unified API for a reason.

But we'll need to keep [node:title] and [term:name] for BC reasons

Sorry @larowlan, just to clarify - I take it you mean to use $entity->label to replace the existing tokens and not create [node:label] and [term:label] tokens?

Sorry, I misunderstood the question.

Is there a use-case for having a generic label token? e.g. allowing something to dynamically use "[$entity_type_id:label]"

If there is, then i see merit in this. If there's not then we're just duplicating existing tokens right?

Hm, if you're inserting tokens in such a way that you can use variables, surely you no longer need tokens?

Perhaps I should try and get this tabled in a UX meeting... though there are about a dozen questions I have for this subsystem's roadmap and while this issue is simple it doesn't seem like the right place to start.

I can see value in this.

As someone who develops custom Entity Types, it's useful to have the generic label because the Entity Type might not have a title (in the traditional sense of a title field), the label might be programmatically generated based on other fields. So having that flexibility in tokens of being able to grab whatever any given Entity Type uses as the label makes sense to me.

But we'll need to keep [node:title] and [term:name] for BC reasons

I would argue to keep them regardless, as in don't deprecate them.

The way I see it is title and name are individual fields, they should be exposed like any other field would be; It's theoretically possible for [node:title] to contain one value (the value that the user inputted into the title field), where [node:label] might have been modified to contain some different value which might be built using a combination of fields, maybe [node:label] outputs something like #[node:id]: [node:title]. This kind of scenario is easily enabled by #2570593: Allow entities to be subclassed using "bundle classes" where a developer could sub-class say the Article content type and override the ->label() method to produce something other than the simply the value of title.

IMHO the only reason to do this issue is to actually do it in a generic way like the issue title proposes, similar to #2920310: [PP-1] Implement revision tokens for content entities, which would then be blocked on the same issue.

That also makes the label vs title method a non-issue because generic code then must use the generic method.

Just ran into this in Drupal commerce and agree it would still be very helpful to have label available, returning the results from ->label().