Email body policy form should show available TWIG variables

Created on 28 November 2023, about 1 year ago
Updated 12 January 2024, about 1 year ago

Problem/Motivation

The description for BodyAdjuster form says:

This field may support tokens or Twig template syntax – please check the supplied default policy for possible values.

We should instead help people out. This issue covers the tokens - see ✨ Email body policy form should show available TWIG variables Needs work for the tokens.

Steps to reproduce

Edit a policy and add a body element

Workaround

  1. Look at the default installed policy - this will often use most of the available variables
  2. Look at the code in the EmailBuilder. The variables are set with setVariable().

Proposed resolution

1) Add new parameter to the @EmailBuilder annotation: variables = array variable name => description.
2) Make the EmailBuilder definition available in the form

  • Add MailerPolicy::getBuilderDefinition()
  • Deprecate MailerPolicy::getCommonAdjusters(), as it's easy to get from the above
  • In PolicyEditForm::form(), call $this->entity->getBuilderDefinition() and store the result in the form.

3) Use the annotations in BodyEmailAdjuster::settingsForm(). Display the variables with '#type' => 'details', and set #value based on the variables annotation.

Example

ContactPageEmailBuilder:

variables = {
  "form" = "BLAH",
  "form_url" = "BLAH",
  "recipient_name" = "BLAH",
  "recipient_edit_url" = "BLAH",
}

Remaining tasks

User interface changes

API changes

Data model changes

✨ Feature request
Status

Needs work

Version

1.0

Component

Code

Created by

πŸ‡¬πŸ‡§United Kingdom adamps

Live updates comments and jobs are added and updated live.
Sign in to follow issues

Merge Requests

Comments & Activities

  • Issue created by @adamps
  • πŸ‡ΊπŸ‡¦Ukraine abyss

    Updated the title and description as it was misplaced with ✨ Email body policy form should show available TWIG variables Needs work .

  • Assigned to abyss
  • πŸ‡ΊπŸ‡¦Ukraine abyss

    @AdamPS, I added display of TWIG variables in the BodyEmailAdjuster.
    But I would like to clarify, from which version it is better to note that getCommonAdjusters is deprecated, and in which version it should be removed?

  • πŸ‡¬πŸ‡§United Kingdom adamps

    Great thanks I'll take a look. It would be deprecated in 1.4.1 and removed in 2.0.0.

  • Status changed to Needs work about 1 year ago
  • πŸ‡¬πŸ‡§United Kingdom adamps

    Yes it looks very good. I didn't have a chance to test it yet, however I reviewed the code in the MR and made a few simple comments.

  • Status changed to Needs review about 1 year ago
  • πŸ‡ΊπŸ‡¦Ukraine abyss

    @AdamPS, I made changes as per the comments in MR and added a deprecated message for MailerPolicyInterface::getCommonAdjusters.
    If you have any other suggestions, I will be happy to add them.

  • Status changed to Needs work about 1 year ago
  • πŸ‡¬πŸ‡§United Kingdom adamps

    Great thanks, it's better. I tested it now and I like it. I made some more comments in the MR - they should all be quick and easy.

    Two bigger comments:

    1) Variables can also be used in SubjectEmailAdjuster and we should do the same. Please put the code in a function (don't just copy itπŸ˜ƒ) e.g. MailerHelperInterface::showReplacementHelp()

    2) It would be great to have a test. At the end of TestEmailTest::testTest(), add a call $this->submitForm([], 'Edit'); then can check that the page contains the replacement pattern for day.

  • πŸ‡¬πŸ‡§United Kingdom adamps

    Actually the are issues open to use tokens in other places too: e.g. plain text body or addresses. So perhaps we should have the variable/token helpers on the form just once - in PolicyEditForm, after all the adjusters. Then for each adjuster that accepts tokens/variables we can put a message to say that.

  • πŸ‡¬πŸ‡§United Kingdom adamps

    OK if you can do it for the email body then that's already good. We can raise a follow on issue for the other places.

Production build 0.71.5 2024