From 5f68c8c8a0e50f733ba54698e892056db3efab4e Mon Sep 17 00:00:00 2001 From: Tim Otten Date: Thu, 29 Oct 2020 23:59:51 -0700 Subject: [PATCH] dev/core#2141 - "Add Mail Account" - Allow hookable listing of setup links 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 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. Before ------ * 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: * 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 options from the dropbox. The step depends on... * 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. --- CRM/Admin/Page/MailSettings.php | 5 ++++ CRM/Core/BAO/MailSettings.php | 24 +++++++++++++++++ CRM/Mailing/Page/AJAX.php | 26 ++++++++++++++++++ CRM/Mailing/xml/Menu/Mailing.xml | 5 ++++ CRM/Utils/Hook.php | 18 +++++++++++++ templates/CRM/Admin/Page/MailSettings.tpl | 33 ++++++++++++++++++++--- 6 files changed, 107 insertions(+), 4 deletions(-) diff --git a/CRM/Admin/Page/MailSettings.php b/CRM/Admin/Page/MailSettings.php index 6ede83649e..c3dca8c853 100644 --- a/CRM/Admin/Page/MailSettings.php +++ b/CRM/Admin/Page/MailSettings.php @@ -107,6 +107,11 @@ class CRM_Admin_Page_MailSettings extends CRM_Core_Page_Basic { } $this->assign('rows', $allMailSettings); + + $setupActions = CRM_Core_BAO_MailSettings::getSetupActions(); + if (count($setupActions) > 1 || !isset($setupActions['standard'])) { + $this->assign('setupActions', $setupActions); + } } /** diff --git a/CRM/Core/BAO/MailSettings.php b/CRM/Core/BAO/MailSettings.php index e7ea7b196b..26086ea2e8 100644 --- a/CRM/Core/BAO/MailSettings.php +++ b/CRM/Core/BAO/MailSettings.php @@ -23,6 +23,30 @@ class CRM_Core_BAO_MailSettings extends CRM_Core_DAO_MailSettings { parent::__construct(); } + /** + * Get a list of setup-actions. + * + * @return array + * List of available actions. See description in the hook-docs. + * @see CRM_Utils_Hook::mailSetupActions() + */ + public static function getSetupActions() { + $setupActions = []; + $setupActions['standard'] = [ + 'title' => ts('Standard Mail Account'), + 'callback' => ['CRM_Core_BAO_MailSettings', 'setupStandardAccount'], + ]; + + CRM_Utils_Hook::mailSetupActions($setupActions); + return $setupActions; + } + + public static function setupStandardAccount($setupAction) { + return [ + 'url' => CRM_Utils_System::url('civicrm/admin/mailSettings', 'action=add&reset=1', TRUE, NULL, FALSE), + ]; + } + /** * Return the DAO object containing to the default row of * civicrm_mail_settings and cache it for further calls diff --git a/CRM/Mailing/Page/AJAX.php b/CRM/Mailing/Page/AJAX.php index e5b4fb9e8f..5af3033f93 100644 --- a/CRM/Mailing/Page/AJAX.php +++ b/CRM/Mailing/Page/AJAX.php @@ -20,6 +20,32 @@ */ class CRM_Mailing_Page_AJAX { + /** + * Kick off the "Add Mail Account" process for some given type of account. + * + * Ex: 'civicrm/ajax/setupMailAccount?type=standard' + * Ex: 'civicrm/ajax/setupMailAccount?type=oauth_1' + * + * @see CRM_Core_BAO_MailSettings::getSetupActions() + * @throws \CRM_Core_Exception + */ + public static function setup() { + $type = CRM_Utils_Request::retrieve('type', 'String'); + $setupActions = CRM_Core_BAO_MailSettings::getSetupActions(); + $setupAction = $setupActions[$type] ?? NULL; + if ($setupAction === NULL) { + throw new \CRM_Core_Exception("Cannot setup mail account. Invalid type requested."); + } + + $result = call_user_func($setupAction['callback'], $setupAction); + if (isset($result['url'])) { + CRM_Utils_System::redirect($result['url']); + } + else { + throw new \CRM_Core_Exception("Cannot setup mail account. Setup does not have a URL."); + } + } + /** * Fetch the template text/html messages */ diff --git a/CRM/Mailing/xml/Menu/Mailing.xml b/CRM/Mailing/xml/Menu/Mailing.xml index 78ac7ebe06..3c4446704f 100644 --- a/CRM/Mailing/xml/Menu/Mailing.xml +++ b/CRM/Mailing/xml/Menu/Mailing.xml @@ -202,6 +202,11 @@ CRM_Mailing_Page_AJAX::getContactMailings access CiviCRM + + civicrm/ajax/setupMailAccount + CRM_Mailing_Page_AJAX::setup + access CiviCRM,access CiviMail + civicrm/mailing/url CRM_Mailing_Page_Url diff --git a/CRM/Utils/Hook.php b/CRM/Utils/Hook.php index a987971774..4eb7f470bc 100644 --- a/CRM/Utils/Hook.php +++ b/CRM/Utils/Hook.php @@ -1042,6 +1042,24 @@ abstract class CRM_Utils_Hook { ); } + /** + * When adding a new "Mail Account" (`MailSettings`), present a menu of setup + * options. + * + * @param array $setupActions + * Each item has a symbolic-key, and it has the properties: + * - title: string + * - callback: string|array, the function which starts the setup process. + * The function is expected to return a 'url' for the config screen. + * @return mixed + */ + public static function mailSetupActions(&$setupActions) { + return self::singleton()->invoke(['setupActions'], $setupActions, self::$_nullObject, self::$_nullObject, + self::$_nullObject, self::$_nullObject, self::$_nullObject, + 'civicrm_mailSetupActions' + ); + } + /** * This hook is called when composing a mailing. You can include / exclude other groups as needed. * diff --git a/templates/CRM/Admin/Page/MailSettings.tpl b/templates/CRM/Admin/Page/MailSettings.tpl index f7e2bde5c4..18f1d67148 100644 --- a/templates/CRM/Admin/Page/MailSettings.tpl +++ b/templates/CRM/Admin/Page/MailSettings.tpl @@ -58,9 +58,34 @@ {ts}None found.{/ts} {/if} -
- {crmButton q="action=add&reset=1" id="newMailSettings" icon="plus-circle"}{ts}Add Mail Account{/ts}{/crmButton} - {crmButton p="civicrm/admin" q="reset=1" class="cancel" icon="times"}{ts}Done{/ts}{/crmButton} -
+ {if $setupActions} +
+ +
+ {else} +
+ {crmButton q="action=add&reset=1" id="newMailSettings" icon="plus-circle"}{ts}Add Mail Account{/ts}{/crmButton} + {crmButton p="civicrm/admin" q="reset=1" class="cancel" icon="times"}{ts}Done{/ts}{/crmButton} +
+ {/if} + {/if} +{literal} + +{/literal} -- 2.25.1