Skip to content

GitLab

Last edited by totten
Page history

message templates

Goals

This re-cap (circa Jan/Feb 2021) tries to summarize the breadth of different goals floating around for message templates. (Listing is in no particular order)

  • Be able to choose/load the most appropriate template from a list of several templates
    • Match by drafting status
    • Match by locale
    • (WHY: This allows editing/curation by larger teams.)
  • Be able to model inputs required for a given template (metadata)
    • Get a list of expected inputs and types
    • Validate specific inputs against the model
    • (WHY: This allows web GUIs, upgrade advisors, validators, etc.)
  • Be able to process templates with different notations, eg
    • Logic notation: Smarty | TokenProcessor | Twig
    • Layout notation: HTML | Text | Mosaico-JSON-HTML | MJML | Pug
    • (WHY: Maintainability - this allows template notation to evolve without breaking existing customizations)
    • (NOTE: This is not saying that it's good have 20 different notations. It's saying that we're currently hard-coded to 1 notation -- and if we want to evolve to the notation, then that requires a different mentality/rigor.)
  • Be able to compose mail templates from smaller chunks, eg
    • Implemented as tokens, Smarty functions, Smarty includes, Mosaico blocks, or similar
    • Include chunks built by devs (code/extensions)
    • Include chunks built by web-admins (eg tokens or {include}s that pull from DB/MsgTpl)
    • Drag-and-drop aspect?
  • Be able to render with multiple output modes
    • Show a preview
    • Send an email to the intended recipient
    • Send a preview email to a reviewer/tester
    • Generate a PDF
    • (WHY: Maintainability - ensure mechanics of rendering/sync/etc work the same regardless of medium)
  • Be able to sync/update templates via workflows for:
    • Web-based admins (eg update DB content)
    • Installation/upgrade (eg sync File=>DB)
    • Git-based staging/dev/prod (eg sync DB<=>File)
    • (WHY: This enables distribution/collaboration among diff people/teams.)
  • Be able to preview with different examples
    • Curated examples (JSON)
    • Real examples (DB records)
    • Interactive examples (eg form-table or Monaco-JSON)
    • (WHY: This makes it easier to draft/test/validate the complex codes that appear in many templates)
  • Provide backward compatibility with any extension which:
    • Fires an email for a pre-existing core MsgTpl (via sendTemplate())
    • Registers a custom MsgTpl and fire an email (via sendTemplate())
    • Uses hook_alterMailParams(&$params, 'messageTemplate')
    • Uses hook_tokenValues / hook_tokens
    • Uses hook_alterMailContent(&$mailContent)
    • (RELATED: If an extension previously provided a MsgTpl, then it would not have metadata, which may limit how it's used. Need some way to either provide defaults and/or backfill metadata and/or work without metadata.)

Comments

(eileen/wmf) On our priorities:

  • These bits are interesting but not pressing:
    • Interactive examples (eg form-table or Monaco-JSON)
  • These bits are not currently in our scope of work:
    • Be able to process templates with different notations
    • Be able to sync template content