Document why Entity Embed Display Plugins are necessary

Problem/Motivation

I'm reviewing the entirety of embed + entity_embed, for several reasons: cacheability/security, because I helped get the CKEditor Widget system into Drupal core, of which this will likely be one of the most prominent users, etc.

I've got a bunch of patches ready against embed, most are small things, and cleanup. It was very doable to grok embed.

With entity_embed, that's not really the case. You'd think it's "just" a matter of a button in CKEditor that points to a Drupal dialog which allows you to select an entity and a view mode, plus a filter to render the entity in the selected view display on output. That's what I expected. I was very very wrong.

Let me explain the problem with Entity Embed Display Plugins by quoting an IRC conversation:
[talking about the confusing/complex data-embed-settings attribute which has a JSON value, this continues where the IRC conversation snippet in #2628168: Clean up Entity Embed's data model ended]

13:52:28 <WimLeers> slashrsm: It *used* to be simpler. Do you know what exactly triggered this change? Perhaps an issue link?
13:53:01 <slashrsm> WimLeers: This specific settings JSON happened when we switched to field formatters for rendering
13:53:19 <WimLeers> slashrsm: and why was that necessary?
13:53:20 <slashrsm> let me see if I can find the issue
13:53:26 <WimLeers> slashrsm: because that is SUPER COMPLEX AND CONFUSING
13:53:31 <WimLeers> slashrsm: not enough capitals there yet
13:53:54 <WimLeers> Because the "Rendered entity" 'display plugin' is apparently not something of Entity Embed, but just \Drupal\Core\Field\Plugin\Field\FieldFormatter\EntityReferenceEntityFormatter
13:54:19 <WimLeers> And the entity_embed-specific *formatters* must use the  "@EntityEmbedDisplay" annotation.
13:54:19 <slashrsm> WimLeers: flexibility when it comes to display. Requiring configuration of a view mode if a lot of overhead for some things. When you just want to embed a thumbnail of an image or similar.
13:54:22 <WimLeers> Super confusing too.
13:54:36 <WimLeers> "formatters" vs " entity embed displays" vs "display plugins" vs …
13:54:43 <slashrsm> WimLeers: those are just wrappers around field formatters
13:54:57 <slashrsm> for user it looks like they are dealing with field formatters
13:55:18 <slashrsm> we need this wrappers to fake the field
13:55:20 <slashrsm> basically...
13:55:27 <WimLeers> slashrsm: Wouldn't it be possible and vastly simpler to require file_entity and have file_entity provide an entity view builder (and thus entity view display), so that entity_embed could just use that?
13:55:55 <WimLeers> then we'd be back to "entity embed allows you to select an entity and a view mode", and that'd be it
13:56:25 <slashrsm> well... It is not just about files. It is also about other entities. Having to configure view mode if you just want to display entity label with a link to it can be a bit to much
13:58:57 <slashrsm> WimLeers: I think it was this PR https://github.com/drupal-media/entity_embed/pull/21/files
13:58:57 <WimLeers> slashrsm: why?
13:59:02 <WimLeers> slashrsm: why is that too much?
13:59:20 <WimLeers> slashrsm: entity_embed could include entity view displays called "Label" and "Linked label" for core's entity types
13:59:54 <WimLeers> slashrsm: the whole point of entity view displays is that they are what define the different ways an entity can be rendered
14:00:11 <WimLeers> slashrsm: it's a big win that that is consolidated
14:00:21 <WimLeers> slashrsm: entity_embed again fragments that
14:00:23 <slashrsm> WimLeers: it definitely could. But from my experience people really struggle to understand view modes when it comes to rendering simple things. They are used to formatters.
14:00:26 <WimLeers> by layering its own thing on top
14:00:31 <WimLeers> slashrsm: well sure
14:00:37 <WimLeers> slashrsm: people are used to what they're used to
14:00:43 <WimLeers> slashrsm: doesn't mean we can't learn them new things
14:01:02 <slashrsm> WimLeers: don't get me wrong. I agree with your concerns. I am just trying to explain reasoning behind the decision.
14:01:02 <WimLeers> slashrsm: entity view displays *are* the correct abstraction
14:01:05 <WimLeers> They're a perfect match
14:01:32 <WimLeers> https://www.drupal.org/project/entity_view_mode -> 24K sites using it, so it's definitely not a vague thing
14:01:39 <WimLeers> slashrsm: I understand that
14:01:54 <WimLeers> slashrsm: but IMO entity_embed will be an absolutely crucial corner stone in D8 sites
14:02:06 <WimLeers> slashrsm: and so I think it's important that it uses the right concepts
14:02:10 <WimLeers> the abstractions that core provides
14:02:13 <WimLeers> rather than layering on its own
14:02:18 <WimLeers> … which is super complex to understand
14:02:20 <slashrsm> WimLeers: I am not a-priori opposing your point. But we definitely need to have a broader discussion about this. Include more people, ...
14:02:29 <WimLeers> Of course
14:02:51 <WimLeers> slashrsm: Shall I open a d.o issue about this?
14:03:32 <slashrsm> It is complex to understand from DX point of view for sure. But I think it is simpler for end-users. Ah... and we're back to this bug question. Who is our main audience?
14:03:57 <slashrsm> WimLeers: sure, open it. And let's discuss. I will mention it to berdir too while I am still here in Zurich.
14:04:51 <WimLeers> slashrsm: I don't think this is simple for the end user either. https://usercontent.irccloud-cdn.com/file/GhyphJI8/Screen%20Shot%202015-12-03%20at%2014.04.26.pngScreen Shot 2015-12-03 at 14.04.26.png55.9KB • image/png
14:04:56 <WimLeers> This forces *two* choices
14:05:03 <WimLeers> "rendered entity" doesn't mean anything to 99% of users
14:05:07 <WimLeers> nor does "view mode"
14:05:21 <WimLeers> always using entity view displays would remove that first choice altogether
14:05:50 <berdir> WimLeers: we can not always use view displays
14:06:23 <WimLeers> I'd then let the entity_embed config UI allow site builders to blacklist entity view displays, so you can exclude "Search index" for example
14:06:48 <WimLeers> berdir: Why not? If file_entity adds an entity view builder for File entities?
14:07:23 <berdir> WimLeers: that's not in core and even with file_entity, where not yet able to display a video through that
14:07:37 <WimLeers> I know it's not in core. But entity_embed could easily depend on file_entity
14:07:53 <WimLeers> "were not yet able" -> due to time constraints or technical contraints?
14:08:34 <berdir> WimLeers: to be clear, I have a custom module that alters that form and does exactly that, but it's a bit more complicated than that (like I'm filtering the allowed view modes per node type, forcing the display plugin for nodes, forcing a different plugin for image and yet another one for video files
14:08:56 <WimLeers> does exactly what?
14:08:57 <berdir> WimLeers: nobody disagrees with you that the UI needs work and needs to be able to simplify itself for specific use cases. but we need the flexibility
14:09:05 <berdir> it removes the Display As option
14:09:08 <WimLeers> ok
14:09:13 <berdir> I have a call now
14:09:34 <WimLeers> But I'm saying that much of the UX and DX problems are a *consequence* of the choice to have EntityEmbedDisplay plugins
14:09:58 <WimLeers> And I think it'd be worth switching to that because long-term it'll be much, much more maintainable
14:11:18 <berdir> WimLeers: It's not that easy. but happy to continue this discussion later
14:11:28 <WimLeers> k, gl on the call
14:12:57 <berdir> WimLeers: if you want, we can do a call later and I can show you how our simplified UI looks like. but we need that flexibility, we just always only show one option
14:13:45 <WimLeers> *what* flexibility do you need?
14:13:52 <WimLeers> EntityEmbedDisplay plugins?

The screenshot I pasted in the IRC chat:

Proposed resolution

TBD

Remaining tasks

Discuss!

User interface changes

TBD

API changes

TBD

Data model changes

TBD