From d8356d0b4db625fb7165ac01eb4d8c1765306e84 Mon Sep 17 00:00:00 2001
From: Coleman Watts <coleman@civicrm.org>
Date: Tue, 17 Mar 2015 15:47:07 -0400
Subject: [PATCH] CRM-15706 - Add help to various MailingUI fields

---
 js/angular-crm-ui.js                     |  5 +-
 js/angular-crmMailing/directives.js      |  2 +-
 js/angular-crmMailingAB/directives.js    |  1 +
 partials/crmMailing/headerFooter.html    |  4 +-
 partials/crmMailing/mailing.html         |  2 +-
 partials/crmMailing/summary.html         |  4 +-
 partials/crmMailingAB/joint-mailing.html |  6 +--
 partials/crmMailingAB/setup.html         |  4 +-
 templates/CRM/Mailing/MailingUI.hlp      | 62 ++++++++++++++++++++++++
 9 files changed, 77 insertions(+), 13 deletions(-)
 create mode 100644 templates/CRM/Mailing/MailingUI.hlp

diff --git a/js/angular-crm-ui.js b/js/angular-crm-ui.js
index 2ae109d1a0..e59e7427c3 100644
--- a/js/angular-crm-ui.js
+++ b/js/angular-crm-ui.js
@@ -126,7 +126,7 @@
         require: '^crmUiIdScope',
         restrict: 'EA',
         scope: {
-          // {title, name, help}
+          // {title, name, help, helpFile}
           crmUiField: '='
         },
         templateUrl: function(tElement, tAttrs){
@@ -136,7 +136,8 @@
         transclude: true,
         link: function (scope, element, attrs, crmUiIdCtrl) {
           $(element).addClass('crm-section');
-          scope.crmUiHelpFile = scope.$parent.crmUiHelpFile; // propagate default
+          // Inherit helpFile from parent scope if not specified
+          scope.crmUiHelpFile = scope.crmUiField.helpFile || scope.$parent.crmUiHelpFile;
         }
       };
     })
diff --git a/js/angular-crmMailing/directives.js b/js/angular-crmMailing/directives.js
index 646d285848..80a022a327 100644
--- a/js/angular-crmMailing/directives.js
+++ b/js/angular-crmMailing/directives.js
@@ -28,7 +28,7 @@
           });
           scope.crmMailingConst = CRM.crmMailing;
           scope.ts = CRM.ts(null);
-          scope.crmUiHelpFile = 'CRM/Mailing/Form/Upload';
+          scope.crmUiHelpFile = 'CRM/Mailing/MailingUI';
           scope[directiveName] = attr[directiveName] ? scope.$parent.$eval(attr[directiveName]) : {};
           $q.when(crmMetadata.getFields('Mailing'), function(fields) {
             scope.mailingFields = fields;
diff --git a/js/angular-crmMailingAB/directives.js b/js/angular-crmMailingAB/directives.js
index d5f170c58f..7cf79d7313 100644
--- a/js/angular-crmMailingAB/directives.js
+++ b/js/angular-crmMailingAB/directives.js
@@ -21,6 +21,7 @@
           scope.crmMailingConst = CRM.crmMailing;
           scope.crmMailingABCriteria = crmMailingABCriteria;
           scope.ts = CRM.ts(null);
+          scope.crmUiHelpFile = 'CRM/Mailing/MailingUI';
 
           var fieldsModel = $parse(attr[directiveName]);
           scope.fields = fieldsModel(scope.$parent);
diff --git a/partials/crmMailing/headerFooter.html b/partials/crmMailing/headerFooter.html
index 165ecd9812..2e611c5a6c 100644
--- a/partials/crmMailing/headerFooter.html
+++ b/partials/crmMailing/headerFooter.html
@@ -4,7 +4,7 @@ Required vars: mailing, crmMailingConst
 -->
 <div class="crm-block"  ng-form="subform" crm-ui-id-scope>
   <div class="crm-group" ng-controller="EmailBodyCtrl">
-    <div crm-ui-field="{name: 'subform.header_id', title: ts('Mailing Header')}">
+    <div crm-ui-field="{name: 'subform.header_id', title: ts('Mailing Header'), help: 'header'}">
       <select
         crm-ui-id="subform.header_id"
         name="header_id"
@@ -16,7 +16,7 @@ Required vars: mailing, crmMailingConst
         <option value=""></option>
       </select>
     </div>
-    <div crm-ui-field="{name: 'subform.footer_id', title: ts('Mailing Footer')}">
+    <div crm-ui-field="{name: 'subform.footer_id', title: ts('Mailing Footer'), help: 'footer'}">
       <select
         crm-ui-id="subform.footer_id"
         name="footer_id"
diff --git a/partials/crmMailing/mailing.html b/partials/crmMailing/mailing.html
index 4521b29593..f9393d9a3a 100644
--- a/partials/crmMailing/mailing.html
+++ b/partials/crmMailing/mailing.html
@@ -21,7 +21,7 @@ It could perhaps be thinned by 30-60% by making more directives.
         <a crm-icon="disk" ng-click="saveTemplate(mailing)" class="crm-hover-button" title="{{ts('Save As')}}"></a>
       </div>
     </div>
-    <div crm-ui-field="{name: 'subform.fromAddress', title: ts('From'), help: 'id-from_email'}">
+    <div crm-ui-field="{name: 'subform.fromAddress', title: ts('From'), help: 'from_email'}">
       <div ng-controller="EmailAddrCtrl" crm-mailing-from-address="fromPlaceholder" crm-mailing="mailing">
         <select
           crm-ui-id="subform.fromAddress"
diff --git a/partials/crmMailing/summary.html b/partials/crmMailing/summary.html
index 42421103a7..ac96c69c28 100644
--- a/partials/crmMailing/summary.html
+++ b/partials/crmMailing/summary.html
@@ -5,7 +5,7 @@ FIXME: Don't hardcode table-based layout!
 -->
 <div class="crm-block" ng-form="subform" crm-ui-id-scope>
   <div class="crm-group">
-    <div crm-ui-field="{name: 'subform.mailingName', title: ts('Mailing Name')}">
+    <div crm-ui-field="{name: 'subform.mailingName', title: ts('Mailing Name'), help: 'name'}">
       <div>
         <input
           crm-ui-id="subform.mailingName"
@@ -17,7 +17,7 @@ FIXME: Don't hardcode table-based layout!
           name="mailingName" />
       </div>
     </div>
-    <div crm-ui-field="{name: 'subform.campaign', title: ts('Campaign')}" ng-show="crmMailingConst.campNames.length > 0">
+    <div crm-ui-field="{name: 'subform.campaign', title: ts('Campaign'), help: 'id-campaign_id', helpFile: 'CRM/Campaign/Form/addCampaignToComponent'}" ng-show="crmMailingConst.campNames.length > 0">
       <select
         crm-ui-id="subform.campaign"
         name="campaign"
diff --git a/partials/crmMailingAB/joint-mailing.html b/partials/crmMailingAB/joint-mailing.html
index 82aa5c4e50..3786a13b8d 100644
--- a/partials/crmMailingAB/joint-mailing.html
+++ b/partials/crmMailingAB/joint-mailing.html
@@ -62,7 +62,7 @@ processed by Angular; if false, the field will be hidden and completely ignored
     </div>
 
 
-    <div crm-ui-field="{name: 'subform.fromAddress', title: ts('From')}" ng-if="fields.fromAddress">
+    <div crm-ui-field="{name: 'subform.fromAddress', title: ts('From'), help: 'from_email'}" ng-if="fields.fromAddress">
       <span ng-controller="EmailAddrCtrl" crm-mailing-from-address="fromPlaceholder" crm-mailing="abtest.mailings.a">
         <select
           crm-ui-id="subform.fromAddress"
@@ -75,7 +75,7 @@ processed by Angular; if false, the field will be hidden and completely ignored
         </select>
       </span>
     </div>
-    <div crm-ui-field="{name: 'subform.fromAddressA', title: ts('From (A)')}" ng-if="fields.fromAddressA">
+    <div crm-ui-field="{name: 'subform.fromAddressA', title: ts('From (A)'), help: 'from_email'}" ng-if="fields.fromAddressA">
       <span ng-controller="EmailAddrCtrl" crm-mailing-from-address="fromPlaceholder" crm-mailing="abtest.mailings.a">
         <select
           crm-ui-id="subform.fromAddressA"
@@ -88,7 +88,7 @@ processed by Angular; if false, the field will be hidden and completely ignored
         </select>
       </span>
     </div>
-    <div crm-ui-field="{name: 'subform.fromAddressB', title: ts('From (B)')}" ng-if="fields.fromAddressB">
+    <div crm-ui-field="{name: 'subform.fromAddressB', title: ts('From (B)'), help: 'from_email'}" ng-if="fields.fromAddressB">
       <span ng-controller="EmailAddrCtrl" crm-mailing-from-address="fromPlaceholder" crm-mailing="abtest.mailings.b">
         <select
           crm-ui-id="subform.fromAddressB"
diff --git a/partials/crmMailingAB/setup.html b/partials/crmMailingAB/setup.html
index 2e30dd8dca..80f76a2983 100644
--- a/partials/crmMailingAB/setup.html
+++ b/partials/crmMailingAB/setup.html
@@ -4,7 +4,7 @@
       {{ts('A/B testing allows you to send two test mailings to a random subset of your recipients. After collecting and
       comparing metrics, the more successful mailing will be sent to the remaining recipients.')}}
     </div>
-    <div crm-ui-field="{name: 'setupForm.abName', title: ts('Name')}" ng-if="fields.abName">
+    <div crm-ui-field="{name: 'setupForm.abName', title: ts('Name'), help: 'name'}" ng-if="fields.abName">
       <input
         crm-ui-id="setupForm.abName"
         name="abName"
@@ -13,7 +13,7 @@
         placeholder="A/B Test Name"
         required/>
     </div>
-    <div crm-ui-field="{name: 'setupForm.campaign', title: ts('Campaign')}" ng-show="crmMailingConst.campNames.length > 0"
+    <div crm-ui-field="{name: 'setupForm.campaign', title: ts('Campaign'), help: 'id-campaign_id', helpFile: 'CRM/Campaign/Form/addCampaignToComponent'}" ng-show="crmMailingConst.campNames.length > 0"
          ng-if="fields.campaign">
       <select
         crm-ui-id="setupForm.campaign"
diff --git a/templates/CRM/Mailing/MailingUI.hlp b/templates/CRM/Mailing/MailingUI.hlp
new file mode 100644
index 0000000000..fa1cf8fab4
--- /dev/null
+++ b/templates/CRM/Mailing/MailingUI.hlp
@@ -0,0 +1,62 @@
+{*
+ +--------------------------------------------------------------------+
+ | CiviCRM version 4.4                                                |
+ +--------------------------------------------------------------------+
+ | Copyright CiviCRM LLC (c) 2004-2013                                |
+ +--------------------------------------------------------------------+
+ | This file is a part of CiviCRM.                                    |
+ |                                                                    |
+ | CiviCRM is free software; you can copy, modify, and distribute it  |
+ | under the terms of the GNU Affero General Public License           |
+ | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
+ |                                                                    |
+ | CiviCRM is distributed in the hope that it will be useful, but     |
+ | WITHOUT ANY WARRANTY; without even the implied warranty of         |
+ | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
+ | See the GNU Affero General Public License for more details.        |
+ |                                                                    |
+ | You should have received a copy of the GNU Affero General Public   |
+ | License and the CiviCRM Licensing Exception along                  |
+ | with this program; if not, contact CiviCRM LLC                     |
+ | at info[AT]civicrm[DOT]org. If you have questions about the        |
+ | GNU Affero General Public License or the licensing of CiviCRM,     |
+ | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
+ +--------------------------------------------------------------------+
+*}
+{htxt id="name"}
+  <p>
+    {ts}Assign a unique name to each of your mailings. Select a naming convention that will help keep your mailings organized and easy to find when you want to review and compare mailing results. For example, if you do a monthly general-interest newsletter - you might use the following naming convention:{/ts}
+  </p><p>
+  <strong>{ts}General Monthly Newsletter: 200709{/ts}</strong>
+</p>
+{/htxt}
+
+{htxt id ="from_email"}
+  <p>{ts}Select the "FROM" Email Address for this mailing from the dropdown list. Available email addresses are configurable by users with Administer CiviCRM permission. EXAMPLE: "Client Services" &lt;clientservices@example.org&gt;{/ts}</p>
+{if call_user_func(array('CRM_Core_Permission','check'), 'administer CiviCRM') }
+  {capture assign="fromConfig"}{crmURL p="civicrm/admin/options/from_email_address" q="reset=1"}{/capture}
+  <p>{ts 1=$fromConfig}Go to <a href='%1'>Administer CiviCRM &raquo; Communications &raquo; FROM Email Addresses</a> to add or edit email addresses. Make sure these email addresses are valid email accounts with your email service provider.{/ts}</p>
+{else}
+  {ts}Contact your site administrator if you need to use a "FROM" Email Address which is not in the dropdown list.{/ts}
+{/if}
+{/htxt}
+
+{htxt id="html"}
+  <p>{ts}You can choose to send BOTH an <strong>HTML</strong> and a plain <strong>TEXT</strong> version of your mailing, OR you can send a <strong>TEXT</strong> version only.{/ts}</p>
+  <p>{ts}If you create only an <strong>HTML</strong> version, CiviMail will automatically create a <strong>TEXT</strong> version for your recipients who have chosen NOT to receive HTML email.{/ts}</p>
+  <h1>{ts}Required Elements{/ts}</h1>
+  <p>{ts}CiviMail email messages must include an <strong>opt-out</strong> link ("Opt out via web page"), and the <strong>postal address</strong> of your organization. These elements help reduce the chances of your email being categorized as SPAM. They can be included in the main message body OR in a re-usable <strong>message footer</strong>. Refer to the online documentation for details on how to include required links and contact information as well as sample messages.{/ts} {docURL page="Sample CiviMail Messages" resource="wiki"}</p>
+{/htxt}
+
+{htxt id="text"}
+  <p>{ts}You can send your email as a simple text-only message, as an HTML formatted message, or both. Text-only messages are sufficient for most email communication - and some recipients may prefer not to receive HTML formatted messages.{/ts}</p>
+  <p>{ts}HTML messages have more visual impact, allow you to include images, and may be more readable if you are including links to website pages. However, different email programs may interpret HTML formats differently - so use this option cautiously unless you have a template format that has been tested with different web and desktop email programs.{/ts}</p>
+{/htxt}
+
+{htxt id="header"}
+  <p>{ts}You may choose to include a pre-configured Header block above your message.{/ts}</p>
+{/htxt}
+
+{htxt id="footer"}
+  <p>{ts}You may choose to include a pre-configured Footer block below your message. This is a good place to include the required unsubscribe, opt-out and postal address tokens.{/ts}</p>
+{/htxt}
\ No newline at end of file
-- 
2.25.1