dev/core#2141 - "Add Mail Account" - Allow hookable listing of setup links

[totten]

Overview

For certain types of mail accounts -- such as Google Mail and Microsoft Exchange Online -- the setup process may require interaction with a remote web-service. The web-service provides some critical details (like authentication tokens) and some handy details (like their username / email address).

If the site supports one of these services, then this revision will enable a setup process. It alters the "Add Mail Account" action to use a more fine-tuned procedure.

This is a part of the larger epic #18863.

Before

Steps:

• Navigate to "Administer => CiviMail => Mail Accounts".
• Below the table, there is a singular button "Add Mail Account".
• Click the button.
• It opens an empty form for configuring the account.

After

By default, the UX is the same. However, if you have an extension like oauth-client, then it changes:

Steps:

• Navigate to "Administer => CiviMail => Mail Accounts".
• Below the table, there is a select box for "Add Mail Account". It lists different account types.
• Choose one of the dropdown options:
  • If you choose "Standard Mail Account", it opens the empty config form.
  • If you choose "Microsoft Exchange Online", it redirects to MS to get authorization from the user. Then, it redirects and prefills the config form.

Technical Details

This defines a new hook, hook_civicrm_mailSetupActions, e.g.

function mymod_civicrm_mailSetupActions($setupActions) {
  $setupActions['supermail'] = [
    'title' => ts('Super Mail'),
    'callback' => '_mymod_setup',
  ];
}

function _mymod_setup($setupAction) {
  return [
    'url' => '...the-next-setup-page...',
  ];
}

For standard mail accounts, 'the-next-setup-page' is just the normal/existing page. For an OAuth2-based provider like Microsoft, it is the OAuth2 URL. There is an implementation of the hook in #18863 (under ext/oauth-client) -- e.g. the oauth_client_civicrm_mailSetupActions delegates to CRM_OAuth_MailSetup and ultimately loads the mail config from ms-exchange.dist.json

Comments

In the basic/default layout, there is the "Add Mail Account" button and also a "Done" button. The "Done" button is weird. But I left it in the basic/default layout because it's hard to prove that it's weird.

[civibot]

(Standard links)

• If this is your first pull-request for CiviCRM, please browse CONTRIBUTING.md for information about the development and testing processes.
• If you are reviewing this pull-request, you may wish to consult the test sites and the Review Standards (long template, short template).

[eileenmcnaughton]

That looks really clean! It does need documentation although I'm OK merging in advance of that since there is a big documentation task in this Oauth work & I expect you will do that at the end

[totten]

Agree about docs. In the exploratory branch, I'm keeping a WIP/notes commit with some backlog and draft docs, and they'll get polished more as we get closer to merging the overall patchset.

[eileenmcnaughton]

OK - I'm going to merge this to keep it all moving. It will get another round of testing once all merged

[totten]

The follow-up on docs is https://lab.civicrm.org/documentation/docs/dev/-/merge_requests/866