From eafc90f7cfd6e0ef4a3201aa44b6316f28dcd02c Mon Sep 17 00:00:00 2001
From: Tim Otten <totten@civicrm.org>
Date: Sat, 5 Feb 2022 13:47:19 -0800
Subject: [PATCH] authx.setting.php - Add/tweak help text so it appears on the
 settings page.

---
 ext/authx/settings/authx.setting.php | 25 ++++++++++++++++++++-----
 1 file changed, 20 insertions(+), 5 deletions(-)

diff --git a/ext/authx/settings/authx.setting.php b/ext/authx/settings/authx.setting.php
index 464c1ac7c0f4..67d20f82a27c 100644
--- a/ext/authx/settings/authx.setting.php
+++ b/ext/authx/settings/authx.setting.php
@@ -18,7 +18,16 @@
  */
 $_authx_settings = function() {
   $weight = 10;
-  $flows = ['param', 'header', 'xheader', 'login', 'auto', 'script', 'pipe', 'legacyrest'];
+  $flows = [
+    'auto' => ts('Auto Login'),
+    'header' => ts('HTTP Header'),
+    'login' => ts('HTTP Session Login'),
+    'param' => ts('HTTP Parameter'),
+    'xheader' => ts('HTTP X-Header'),
+    'legacyrest' => ts('Legacy REST'),
+    'pipe' => ts('Pipe'),
+    'script' => ts('Script'),
+  ];
   $basic = [
     'group_name' => 'CiviCRM Preferences',
     'group' => 'authx',
@@ -39,13 +48,13 @@
     ],
     'default' => ['site_key', 'perm'],
     'title' => ts('Authentication guard'),
-    'help_text' => ts('Enable an authentication guard if you want to limit which users may authenticate via authx. The permission-based guard is satisfied by checking user permissions. The key-based guard is satisfied by checking the secret site-key. The JWT guard is satisfied if the user presents a signed token. If there are no guards, then any user can authenticate.'),
+    'description' => ts('Enable an authentication guard if you want to limit which users may authenticate via authx. The permission-based guard is satisfied by checking user permissions. The key-based guard is satisfied by checking the secret site-key. If there are no guards, then any user can authenticate.'),
     'pseudoconstant' => [
       'callback' => ['\Civi\Authx\Meta', 'getGuardTypes'],
     ],
     'settings_pages' => ['authx' => ['weight' => $weight]],
   ];
-  foreach ($flows as $flow) {
+  foreach ($flows as $flow => $flowLabel) {
     $weight = $weight + 10;
     $s["authx_{$flow}_cred"] = $basic + [
       'name' => "authx_{$flow}_cred",
@@ -57,7 +66,7 @@
         'class' => 'huge crm-select2',
       ],
       'default' => ['jwt'],
-      'title' => ts('Acceptable credentials (%1)', [1 => $flow]),
+      'title' => ts('Acceptable credentials (%1)', [1 => $flowLabel]),
       'pseudoconstant' => [
         'callback' => ['\Civi\Authx\Meta', 'getCredentialTypes'],
       ],
@@ -72,7 +81,7 @@
         'class' => 'huge crm-select2',
       ],
       'default' => 'optional',
-      'title' => ts('User account requirements (%1)', [1 => $flow]),
+      'title' => ts('User account requirements (%1)', [1 => $flowLabel]),
       'help_text' => NULL,
       'pseudoconstant' => [
         'callback' => ['\Civi\Authx\Meta', 'getUserModes'],
@@ -89,6 +98,12 @@
   $s['authx_xheader_cred']['default'] = ['jwt', 'api_key'];
   $s['authx_pipe_cred']['default'] = ['jwt', 'api_key'];
 
+  // Oof. Attach description to one flow. This is silly - should be on all flows. But, at time of writing, the auto-generated `settings_pages` would become unreadable.
+  $finalFlow = key(array_slice($flows, -1));
+  $seeAlso = ts('See also: <a %1>Authentication Documentation</a>', [1 => 'href="https://docs.civicrm.org/dev/en/latest/framework/authx/" target="_blank"']);
+  $s["authx_{$finalFlow}_cred"]['description'] = ts('Specify which types of <em>credentials</em> are allowed in each <em>authentication flow</em>.') . '<br/>' . $seeAlso;
+  $s["authx_{$finalFlow}_user"]['description'] = ts('CiviCRM <em>Contacts</em> are often attached to CMS <em>User Accounts</em>. When authenticating a <em>Contact</em>, should it also load the <em>User Account</em>?') . '<br/>' . $seeAlso;
+
   return $s;
 };