Bojan's thouhgts on how to improve Message

[RoySegall]

Well... it's clearly something special to get an email from @bojanz the great but I'll share the email:

I've been a heavy Message user in D7, for both Commerce Kickstart v2, and various other projects. Commerce Message remains the canonical way for people to do emails with Commerce 1.x. It actually satisfies two very different use cases for us:

1. Order receipt emails
2. Activity logs for orders

No. 1 proved to be tricky because of the inflexibility of tokens and the lack of conditionals in message templates. Both of these especially visible cause Commerce 1.x uses the same order type for shippable and non-shippable products. People wanted to output different headings and pieces based on whether there was a shipping address or not.

So we decided to rethink emails in 2.x. Unfortunately, tokens made no progress since D7. Fago made the TypedData module which provided automatic twiggy tokens: http://d8rules.org/news/d8rules-reaches-milestone-2, and I was very tempted to use that. The problem of conditionals still remained. The solution was to start using Twig templates for emails. It gave us conditionals, and a well understood way to output data (or provide your own via preprocess hooks).

I think this is something Message can easily improve: Make each message template partial an inline Twig template, rendered the same way the inline_template form element is rendered. It probably wouldn't even interfere with the text formats. The question remains though whether an editing UI is desired here. After all, the email template can get pretty long, and people are generally fine with overriding Twig templates for pages in other use cases.
So, that left us focusing on the activity logs, which are much closer to the most frequent (and original?) Message use case. It's the reason why OpenSocial uses Message, for example.

The problem with No. 2 is the admin experience. Let's say that an order log has 20 potential events/messages. That means 20 message template entities, with matching field instances for the order reference field. They also need to be grouped by purpose (a message category). This concept was removed from Message 8.x, Amitai said that the use case was Commerce Guys specific, but I'm assuming bringing that back would not be a problem.

The problem of reference fields could be solved by Message having a default entity reference field, if it can make an assumption that there's always a related entity. This reference can be a
dynamic_entity_reference, or it could be faked with separate entity_id and entity_type base fields.

The problem of 20 templates for 20 events remains. We have 20 pages and 20 bundles for what is essentially the same use case. I thought of several ways to address what:

1. Provide a UI that edits all message template belonging to the same category at once. We did this for product attributes in Commerce.
2. Make template partials have machine names, which allows them to be targeted from code. A message would need to store both the template and the partial ID though.

Note how the UX of #1 and #2 ends up feeling very similar. The difference is in the number of config entities and whether each template gets its own bundle.

In Commerce 2.x we've been moving away from UIs and user-editable configuration for a while now Our workflows are in YAML plugins, not in config entities like core did for 8.3.x. This way we emphasized that the module owns them, not the user. We also sidestepped the problem of a user removing something that's in use.

So my last idea was to experiment with making message templates defined in YAML, discovered as plugins. That brings all order templates into the same file. The potx module can automatically discover and translate the template strings if we tell it which key to look at (via yaml_translation_patterns.yml). No partials, each template is an inline Twig template, thus no tokens. The message arguments get passed to the template along with the referenced entity. A client needed an activity log, so Matt went ahead and built that: drupalcommerce/commerce#589 I am happy with its simplicity, but it's not an approach I expect every Message user to be happy with (no UI, no partials).

Us moving forward with this approach does not mean we're not interested in discussing Message improvements, and helping implement them. Hence this email. Apologies for its length. I'm fine with us discussing this throughout 2017, it's of no urgency.

[RoySegall]

We have some projects in Gizra which uses the Message module a lot - for emails and logs. And as the project growing the Message module get more "abused" and this is something we need to solve widely. Not just for Commerce Kickstart.

I would like to suggest plugins as our friend for your problems:

I think this is something Message can easily improve: Make each
message template partial an inline Twig template

I think, in this case we can make a plugin which will render the message text(email title and body) using twig files. You said back then that you need a way to pass values easily to the twig template and in this case, our plugin will have a method that will inject the values to the twig template thus removing the need for tokens.

The problem with #2 is the admin experience. Let's say that an order log has 20
potential events/messages

I think plugins is the answer in here as well. But in this case you could create a message type which relies on small plugins(YML or annotation based). From the UI we can order the text of the message by drag and drop in a similar way to how we create view mode.

[bojanz]

Extensibility is a fine goal to have, but the question here is more about what the default UX and DX should be for the main Message use cases.

[RoySegall]

@jhedstrom Is a heavy contributor. Any thoughts?

[jhedstrom]

I've been thinking this over, I still don't have clear thoughts on all described above, but I do think cleaning some or all of this up for a 2.x release would be worth pursuing.

I particularly like the idea of partials with machine names, as well as twig templating. I would want to retain some ability to use a WYSIWYG for editing though, as many of these are used for emails that folks want highly styled (and don't want to have to wait on a dev or themer for changes, etc).

I don't want to change it up this much in the 1.x branch as I hope to get that to a stable release soon. (And I wouldn't want the ~700 or so folks using the alpha to have to deal with that big of a change.)