crm.fsf.org/20131203/files/sites/all/modules-new/webform_civicrm/includes/wf_crm_admin_help.inc

   1 <?php
   2
   3 /**
   4  * @file
   5  * Admin form inline-help.
   6  */
   7
   8 /**
   9  * Class wf_crm_admin_help
  10  * Adding a static function to this class with the same name as a field will magically add pop-up help for that field to the admin form.
  11  */
  12 class wf_crm_admin_help {
  13
  14   static function intro() {
  15     print '<p>' .
  16       t('Create anything from a simple newsletter signup, to a complex multi-step registration system.') .
  17       '</p><strong>' .
  18       t('Getting Started:') .
  19       '</strong><ul>' .
  20       '<li>' . t('Enable fields for one or more contacts.') . '</li>' .
  21       '<li>' . t('Arrange and configure those fields on the "Webform" tab.') . '</li>' .
  22       '<li>' . t('Click the blue help icons to learn more.') . '</li>' .
  23       '<li><a href="http://wiki.civicrm.org/confluence/display/CRMDOC/Webform+CiviCRM+Integration" target="_blank">' . t('Read the instructions.') . '</a></li>' .
  24       '</ul>';
  25   }
  26
  27   static function contact_existing() {
  28     print '<p>' .
  29       t('Gives many options for how this contact can be autofilled or selected. From the Webform tab you can edit this field to configure:') .'</p><ul>' .
  30       '<li>' . t('Widget: Determine whether to expose this field to the form as an autocomplete or select element, or hide it and pick the contact automatically.') . '</li>' .
  31       '<li>' . t('Default Value: Select a contact based on the current user, relationships, or other options.') . '</li>' .
  32       '<li>' . t('Filters: Limit the list of available choices from which this contact may be autofilled or selected.') . '</li>' .
  33       '<li>' . t('Show/Hide Fields: Control which other fields the user is allowed to edit and which will be hidden.') . '</li>' .
  34       '</ul>';
  35   }
  36
  37   static function contact_employer_id() {
  38     print '<p>' .
  39       t('Choose a webform contact of type "Organization" to be the employer for this individual.') .
  40       '</p><p>' .
  41       t('Use the "Existing Contact" field for that organization to enable autocomplete or selection of employers.') .
  42       '</p><p>' .
  43       t('You can also autofill the employer by configuring the organization\'s "Existing Contact" default value to be "Employer" relationship to Contact 1.') .
  44       '</p>';
  45   }
  46
  47   static function contact_image_URL() {
  48     print '<p>' .
  49       t('Allows an image to be associated with a contact. This image will appear in CiviCRM, but the file is stored in Drupal. If the webform submission or entire webform were to be deleted, the image would be lost.') .
  50       '</p>';
  51   }
  52
  53   static function contact_contact_id() {
  54     print '<p>' .
  55       t('This hidden field can be used to as a token to generate links, for example to include an email link back to this form to update their info.') .
  56       '</p>';
  57   }
  58
  59   static function contact_external_identifier() {
  60     self::contact_contact_id();
  61   }
  62
  63   static function contact_source() {
  64     print '<p>' .
  65       t('This field will override the "Source Label" in "Additional Options".') .
  66       '</p>';
  67   }
  68
  69   static function contact_cs() {
  70     self::contact_contact_id();
  71   }
  72
  73   static function matching_rule() {
  74     print '<p>' .
  75       t('This determines how an <em>unknown</em> contact will be handled when the webform is submitted.') .
  76       '</p><ul>' .
  77       '<li>' . t('Select the "Default Unsupervised" rule for the same duplicate matching used by CiviCRM event registration &amp contribution forms.') . '</li>' .
  78       '<li>' . t('Select a specific rule to customize how matching is performed.') . '</li>' .
  79       '<li>' . t('Or select "- None -" to always create a new contact.') . '</li>' .
  80       '</ul><p>' .
  81       t('Note: Matching rules are only used if the contact is not already selected via "Existing Contact" field.') .
  82       '</p>';
  83   }
  84
  85   static function address_master_id() {
  86     print '<p>' .
  87       t('When selected, will hide fields for this address and use those of the other contact.') .
  88       '</p><p>' .
  89       t('Tip: In many use-cases it is desirable to show this field as a single checkbox. You can configure that by editing the field and removing all but one option (the one this contact is allowed to share) and re-labelling it something like "Same as my address".') .
  90       '</p>';
  91   }
  92
  93
  94   static function contribution_contribution_page_id() {
  95     print '<p>' .
  96       t("It is recommended to <a !link>create a new contribution page</a> solely for webform use. When configuring the page, most options will be irrelevant (such as profiles, premiums, widgets, recurring, etc.). Only the following need to be configured:",
  97         array('!link' => 'target="_blank" href="' . url('civicrm/admin/contribute/add', array('query' => array('reset' => 1, 'action' => 'add'))) . '"')) .
  98       '</p><ul>' .
  99       '<li>' . t('Title: Displayed on the webform.') . '</li>' .
 100       '<li>' . t('Financial Type: Controls overall contribution type.') . '</li>' .
 101       '<li>' . t('Currency: Sets currency for all payment fields on this form.') . '</li>' .
 102       '<li>' . t('Payment Processors: Controls list of options here.') . '</li>' .
 103       '<li>' . t('Contribution Amounts: Must be enabled with a label and Allow Other Amounts checked.') . '</li>' .
 104       '<li>' . t('Email Receipt: Configure email receipts from this webform.') . '</li>' .
 105       '</ul>';
 106   }
 107
 108   static function contribution_payment_processor_id() {
 109     print '<p>' .
 110       t('Supported payment processors enabled on the contribution page are available here. "Pay Later" option allows the user to purchase events/memberships without entering a credit card.') .
 111       '</p><p>' .
 112       t("Note that only on-site credit card processors are currently supported on Webforms. Services that redirect to an external website, such as Paypal Standard, are not supported. Recurring payments are not supported.") .
 113       '</p>';
 114   }
 115
 116   static function contribution_total_amount() {
 117     print '<p>' .
 118       t('This amount will be in addition to any paid events and memberships.') .
 119       '</p>';
 120     self::fee();
 121   }
 122
 123   static function participant_fee_amount() {
 124     print '<p>' .
 125       t('Price for this event. If multiple events or participants are registered with this field, the amount will be multiplied per-person, per-event.') .
 126       '</p><p>' .
 127       t('Note that any event prices you have configured in CiviCRM are not imported into the Webform - you will need to reconfigure them here.') .
 128       '</p>';
 129     self::fee();
 130   }
 131
 132   static function fee() {
 133     print '<p>' .
 134       t('Once added to the webform, this field can be configured in a number of ways by changing its settings.') .
 135       '</p><strong>' .
 136       t('Possible Widgets:') .
 137       '</strong><ul>' .
 138       '<li>' . t('Number (default): Allow the user to enter an amount, optionally constrained by min, max, and increments.') . '</li>' .
 139       '<li>' . t('Hidden: Set the amount without giving the user a choice.') . '</li>' .
 140       '<li>' . t('Select/Radios: Allow the user to choose from one of several options.') . '</li>' .
 141       '<li>' . t('MultiSelect/Checkboxes: Each choice the user selects will be added together.') . '</li>' .
 142       '<li>' . t('Grid: Configure multiple items and quantities.') . '</li>' .
 143       '</ul>';
 144   }
 145
 146   static function participant_reg_type() {
 147     print '<p>' .
 148       t('Registering as a group will set Contact 1 as the primary registrant. Registering participants separately gives finer control over which contacts register for what events.') .
 149       '</p><p>' .
 150       t('With only one contact on the form, there is no difference between these two options.') .
 151       '</p>';
 152   }
 153
 154   static function participant_event_id() {
 155     print '<p>' .
 156       t('Events can be selected here without giving the user a choice, or this field can be added to the form ("User Select").') .
 157       '</p><p>' .
 158       t('Click the + button to choose multiple events.') .
 159       '</p><p>' .
 160       t('On the form, this field could be represented as either single or multiselect (checkboxes or radios). Note: enabling this field as a multiselect (checkboxes) should only be done if all selectable events will have the same price, role, custom data, etc.') .
 161       '</p><p>' .
 162       t('"Live Options" can be enabled to keep the field up-to-date with all your organization\'s events, or you can hand-pick the events you wish to show.') .
 163       '</p>';
 164   }
 165
 166   static function participant_status_id() {
 167     print '<ul><li>' .
 168       t('In "Automatic" mode, status will be set to "Registered" (or "Pending" if the user chooses to "Pay Later" for events with a fee). The user will be able to cancel registration by re-visiting the form and de-selecting any events they are registered for.') .
 169       '</li><li>' .
 170       t('If a status is selected here, events will be autofilled only if the participant has that status.') .
 171       '</li><li>' .
 172       t('If this field is exposed to the webform ("User Select"), events will be autofilled only if the particiant status among the enabled options.') .
 173       '</li></ul>';
 174   }
 175
 176   static function reg_options_show_remaining() {
 177     print '<p>' .
 178       t('Display a message at the top of the form for each event with a registration limit or past end date.') .
 179       '</p>';
 180   }
 181
 182   static function reg_options_validate() {
 183     print '<p>' .
 184       t('Will not allow the form to be submitted if user registers for an event that is ended or full.') .
 185       '</p>';
 186   }
 187
 188   static function reg_options_block_form() {
 189     print '<p>' .
 190       t('Hide webform if all the events for the form are full or ended.') .
 191       '</p>';
 192   }
 193
 194   static function reg_options_disable_unregister() {
 195     print '<p>' .
 196       t('If this is selected, on "User Select mode", participants will not be unregistered from unchecked events.') .
 197       '</p>';
 198   }
 199
 200   static function reg_options_allow_url_load() {
 201     print '<p>' .
 202       t('Allow events in "User Select" mode to be auto-filled from URL.') .
 203       '</p>'.'<br /><p>'.t('Example for "Register all":') .
 204       '<br /><code>' . url("node", array('absolute' => TRUE)) . '/{node.nid}?event1={event1.event_id},{event2.event_id}</code></p><br />'.
 205       t('Example for "Register separately":') .
 206       '<br /><code>' . url("node", array('absolute' => TRUE)) .
 207       '/{node.nid}?c1event1={event1.event_id},{event2.event_id}&amp;c2event1={event3.event_id}</code></p>';
 208   }
 209
 210   static function reg_options_show_past_events() {
 211     print '<p>' .
 212       t('To also display events that have ended, choose an option for how far in the past to search.') .
 213       '</p>';
 214   }
 215
 216   static function reg_options_show_future_events() {
 217     print '<p>' .
 218       t('To also display events in the future, choose an option for how far in the future to search.') .
 219       '</p>';
 220   }
 221
 222   static function reg_options_title_display() {
 223     print '<p>' .
 224       t('Controls how events are displayed. Date formats can be further configured in <a !link>CiviCRM Date Settings</a>',
 225         array('!link' => 'target="_blank" href="' . url('civicrm/admin/setting/date', array('query' => array('reset' => 1))) . '"')
 226       ) .
 227       '</p><p>' .
 228       t('Note: End-date will automatically be omitted if it is the same as the start-date.') .
 229       '</p>';
 230   }
 231
 232   static function membership_membership_type_id() {
 233     print '<p>' .
 234       t('Fee will be calculated automatically based on selected membership type and number of terms chosen. A contribution page must be enabled to collect fees.') .
 235       '</p>';
 236   }
 237
 238   static function membership_status_id() {
 239     print '<p>' .
 240       t('If number of terms is enabled, status can be calculated automatically based on new/renewal status and payment.') .
 241       '</p>';
 242   }
 243
 244   static function membership_num_terms() {
 245     print '<p>' .
 246       t('Membership dates will be filled automatically by selecting terms. This can be overridden by entering dates manually.') .
 247       '</p><p>' .
 248       t('Note: Number of terms is required to calculate membership fees for paid memberships.') .
 249       '</p><p>'.
 250       t('If you choose to enter dates manually, enabling membership fee field will provide the price. Otherwise the membership will be free') .
 251       '</p>';
 252   }
 253
 254   static function membership_fee_amount() {
 255     print '<p>' .
 256       t('Price for this membership per term. If this field is enabled, the default minimum membership fee from CiviCRM membership type settings will not be loaded.') .
 257       '</p><p>' .
 258       t('Note that if this field is enabled, the default minimum membership fee from CiviCRM membership type settings will not be loaded.') .
 259       '</p>';
 260     self::fee();
 261   }
 262
 263   static function multiselect_options() {
 264     print '<p>' .
 265       t('Click the + button to select more than one option.') .
 266       '</p><p>' .
 267       t('You may set options here and/or add this element to the webform ("User Select"). Options chosen here will be applied automatically and will not appear on the form.') .
 268       '</p>';
 269   }
 270
 271   static function webform_label() {
 272     print '<p>' .
 273       t('Labels help you keep track of the role of each contact on the form. For example, you might label Contact 1 "Parent", Contact 2 "Spouse" and Contact 3 "Child".') .
 274       '</p><p>' .
 275       t("Labels do not have to be shown to the end-user. By default they will be the title of each contact's fieldset, but you may rename (or remove) fieldsets without affecting this label.") .
 276       '</p>';
 277   }
 278
 279   static function activity_target_contact_id() {
 280     print '<p>' .
 281       t('Which contacts should be tagged as part of this activity?') .
 282       '</p>';
 283     self::contact_reference();
 284   }
 285
 286   static function activity_source_contact_id() {
 287     print '<p>' .
 288       t('Choose "automatic" to have this activity attributed to the current user (or contact 1 if the user is anonymous).') .
 289       '</p>';
 290     self::contact_reference();
 291   }
 292
 293   static function activity_assignee_contact_id() {
 294     civicrm_initialize();
 295     print '<p>';
 296     if (CRM_Core_BAO_Setting::getItem(CRM_Core_BAO_Setting::SYSTEM_PREFERENCES_NAME, 'activity_assignee_notification')) {
 297       print t('A copy of this activity will be emailed to the assignee.');
 298     }
 299     else {
 300       print t('Assignee notifications are currently disabled in CiviCRM; no email will be sent to the assignee.');
 301     }
 302     print '</p>';
 303     self::contact_reference();
 304   }
 305
 306   static function activity_duration() {
 307     print '<p>' .
 308       t('Total time spent on this activity (in minutes).') .
 309       '</p>';
 310   }
 311
 312   static function existing_activity_status() {
 313     print '<p>' .
 314       t('If a matching activity of the chosen type already exists for Contact 1, it will be autofilled and updated.') .
 315       '</p><p>' .
 316       t('Note: an activity can also be autofilled by passing "activity1", etc. in the url.') .
 317       '</p>';
 318   }
 319
 320   static function existing_case_status() {
 321     print '<p>' .
 322       t('If a matching case of the chosen type already exists for the client, it will be autofilled and updated.') .
 323       '</p><p>' .
 324       t('Note: a case can also be autofilled by passing "case1", etc. in the url.') .
 325       '</p>';
 326   }
 327
 328   static function existing_grant_status() {
 329     print '<p>' .
 330       t('If a matching grant of the chosen type already exists for the applicant, it will be autofilled and updated.') .
 331       '</p><p>' .
 332       t('Note: a grant can also be autofilled by passing "grant1", etc. in the url.') .
 333       '</p>';
 334   }
 335
 336   static function file_on_case() {
 337     print '<p>' .
 338       t('Add this activity to either a specific case from this webform, or an already existing case based on matching criteria.') .
 339       '</p><p>' .
 340       t('These options will not open a new case; configure the "Cases" section to do so.') .
 341       '</p>';
 342   }
 343
 344   static function case_medium_id() {
 345     print '<p>' .
 346       t('Medium for activities added to cases from this webform.') .
 347       '</p>';
 348   }
 349
 350   static function contact_reference() {
 351     print '<p>' .
 352       t('This is a contact reference field. Webform gives you a great deal of flexibility about how this field is displayed:') .
 353       '</p><ul>' .
 354       '<li>' . t('First choose a contact on this webform as the target for this field (or add a new contact to the form for that purpose).') . '</li>' .
 355       '<li>' . t('To enable a selection of contacts, enable the "Existing Contact" field for the selected contact.') . '</li>' .
 356       '<li>' . t('This allows the contact to be selected on the form via autocomplete or dropdown select, or hidden and set to always be the same contact.') . '</li>' .
 357       '<li>' . t('In rare cases you might want to expose the list of webform contacts ("User Select").') . '</li>' .
 358       '<li>' . t('There are many more possibilities, see "Existing Contact" field help for more information.') . '</li>' .
 359       '</ul>';
 360   }
 361
 362   static function fieldset_relationship() {
 363     print '<p>' .
 364       t('Relationships are created from higher-number contacts to lower-number contacts.') .
 365       '</p><p>' .
 366       t("Example: to create a relationship between Contact 3 and Contact 4, go to Contact 4's tab and select Number of Relationships: 3. This will give you the option to create relationships between Contact 4 and Contacts 1, 2, and 3, respectively.") .
 367       '</p>';
 368   }
 369
 370   static function contact_creation() {
 371     print '<p>' .
 372       t('CiviCRM requires at minimum a name or email address to create a new contact.') .
 373       '</p><p>' .
 374       t("Webform contacts that do not have these fields can be used for selection of existing contacts but not creating new ones.") .
 375       '</p>';
 376   }
 377
 378   static function contact_component_widget() {
 379     print '<ul>
 380       <li>' . t('Autocomplete will suggest names of contacts as the user types. Good for large numbers of contacts.') . '</li>
 381       <li>' . t('A select list will show all possible contacts in a dropdown menu. Good for small lists - use filters.') . '</li>
 382       <li>' . t('A static element will select a contact automatically without giving the user a choice. Use in conjunction with a default value setting or a cid passed in the url.') . '</li>
 383       </ul>';
 384   }
 385
 386   static function contact_component_hide_fields() {
 387     print '<p>' .
 388       t('When an existing contact is selected or prepopulated, which fields should the user not be allowed to edit?') .
 389       '</p><p>' .
 390       t("This is useful for preventing changes to existing data.") .
 391       '</p>';
 392   }
 393
 394   /**
 395    * Get help for a custom field
 396    */
 397   static function custom($param) {
 398     list( , $id) = explode('_', $param);
 399     if (!is_numeric($id)) {
 400       return;
 401     }
 402     civicrm_initialize();
 403     module_load_include('inc', 'webform_civicrm', 'includes/utils');
 404     $info = wf_civicrm_api('custom_field', 'getsingle', array('id' => $id));
 405     if (!empty($info['help_pre'])) {
 406       print '<p>' . $info['help_pre'] . '</p>';
 407     }
 408     if (!empty($info['help_post'])) {
 409       print '<p>' . $info['help_post'] . '</p>';
 410     }
 411   }
 412
 413   /**
 414    * Get help for a fieldset
 415    */
 416   static function fieldset($param) {
 417     list( , $set) = explode('_', $param);
 418     civicrm_initialize();
 419     module_load_include('inc', 'webform_civicrm', 'includes/utils');
 420     $sets = wf_crm_get_fields('sets');
 421     if (!empty($sets[$set]['help_text'])) {
 422       print '<p>' . $sets[$set]['help_text'] . '</p>';
 423     }
 424   }
 425
 426   /**
 427    * Copied from Core CiviCRM's templates/notifications.tpl
 428    * @return string
 429    */
 430   static function helpTemplate() {
 431     return '
 432     <div class="crm-container">
 433       <div id="crm-notification-container" style="display:none">
 434         <div id="crm-notification-alert" class="#{type}">
 435           <div class="icon ui-notify-close" title="' . t('close') . '"> </div>
 436           <a class="ui-notify-cross ui-notify-close" href="#" title="' . t('close') . '">x</a>
 437           <h1>#{title}</h1>
 438           <div class="notify-content">#{text}</div>
 439         </div>
 440       </div>
 441     </div>';
 442   }
 443
 444   /**
 445    * Add Civi help icon to a FAPI field
 446    * @param array $field
 447    * @param string $topic
 448    * @param string|null $title
 449    */
 450   static function addHelp(&$field, $topic, $title = NULL) {
 451     $title = $title ? $title : $field['#title'];
 452     $field['#title'] .= ' &nbsp;' . self::helpIcon($topic, $title);
 453   }
 454
 455   static function helpIcon($topic, $title) {
 456     return '<span class="crm-container"><a class="helpicon" href="#' . $topic . '" title="' . $title .'">&nbsp;</a></span>';
 457   }
 458 }
 459
 460 /**
 461  * Ajax page callback
 462  * @param string $topic
 463  */
 464 function wf_crm_admin_help($topic) {
 465   if (method_exists('wf_crm_admin_help', $topic)) {
 466     wf_crm_admin_help::$topic();
 467   }
 468   elseif (strpos($topic, 'custom_') === 0) {
 469     wf_crm_admin_help::custom($topic);
 470   }
 471   elseif (strpos($topic, 'fieldset_') === 0) {
 472     wf_crm_admin_help::fieldset($topic);
 473   }
 474   exit();
 475 }