README.txt

   1
   2 CONTACT IMPORTER
   3 ================
   4
   5 Contact Importer provides a form for your users to enter their email address and password. The
   6 contacts from their address book are then retreived.
   7
   8 Contact Importer can be used with any Drupal form. No codding necessary. It can be used with
   9 an invite module, a user import module, an emailing module, or anything else that you can
  10 think of.
  11
  12 The current release interfaces with the Octazen or Open Inviter retrieval services. But the
  13 architecture is modular and can be very easily extended to use other retrieval services such
  14 as Contact Mines, ImproSys, or IpInvite.
  15
  16
  17 Developed By
  18 ------------
  19
  20 Advomatic LLC
  21 http://advomatic.com
  22
  23 and
  24
  25 Scott Hadfield
  26
  27
  28 Sponsored By
  29 ------------
  30
  31 Democrats.com
  32 http://democrats.com
  33
  34
  35 INSTALLATION
  36 ============
  37
  38 1) Unpack the module into your sites/all/modules directory.
  39 2) Go to
  40     Administer � Modules
  41    Enable the Contact Importer module and at least one
  42    Retrieval Engine module.
  43 3) Enable permissions at
  44     Administer � People � Permissions
  45    for 'administer contact importer' and 'access contact importer'.
  46 4) Go to
  47     Administer � Configuration � Web Services � Contact Importer
  48 5) Review the documentation link for the Retrieval Engine(s) that you have enabled and install the
  49    libraries for at least one engine.
  50 6) Clear the cache at:
  51     Administer � Configuration � Web Services � Contact Importer � Settings
  52 7) Choose which engines will manage which providers at
  53     Administer � Configuration � Web Services � Contact Importer � Providers
  54 8) Integrate Contact Importer into your forms (see below).
  55
  56
  57 CONSIDERATIONS
  58 ==============
  59
  60 It should be noted that using Contact Importer makes it very easy for your users to send email
  61 to / import a lot of people.  It is recommended that you:
  62 - have a CAPTCHA or a similar method in place to prevent spambots from using your form to send
  63   spam.
  64 - limit the number of emails/contacts that anonymous users can send/import.
  65 - have a throttling and/or queuing mechanism in place so that if a user uses Contact Importer to
  66   insert 500 email addresses into your textbox, your server is not brought to its knees when the
  67   form is submitted.
  68
  69
  70 TROUBLESHOOTING
  71 ===============
  72
  73 If you change or add files or libraries, and your changes aren't reflected in Contact Importer,
  74 try clearing the cache at:
  75   Administer � Configuration � Web Services � Contact Importer � Settings
  76
  77
  78 OPTIONAL EXTRAS
  79 ===============
  80
  81 Contact Importer works best in conjunction with either the Overlay, Lightbox2, or Automodal modules.
  82 http://drupal.org/project/lightbox2
  83 http://drupal.org/project/automodal
  84
  85 Contact Importer will use one of these modules to show a modal pop-up so that the user can import
  86 from her address book without leaving the current page.  In the absence of JavaScript, Contact
  87 Importer degrades to a multistep-form-like method.
  88
  89
  90 INTEGRATE WITH ANY FORM
  91 =======================
  92
  93 Remember that Contact Importer doesn't create any send-to-a-friend (or the like) forms for you,
  94 you already need to have a form on your Drupal site that has a field for email addresses.
  95
  96 1) Enable the Contact Importer Form Integration module
  97 2) Enable Form ID and Field messaging at
  98     Administer � Configuration � Web Services � Contact Importer � Settings
  99 3) Navigate to the page containing your form.  You'll see messages listing each form ID and field
 100    name of all textfields and textareas on the page.  Note the form ID and field name that you want
 101    to use with Contact Importer.
 102 4) Enter the form ID and field name at
 103     Administer � Configuration � Web Services � Contact Importer � Forms
 104 5) Disable Form ID and Field messaging at
 105     Administer � Configuration � Web Services � Contact Importer � Settings
 106
 107
 108 INTEGRATING WITH YOUR FORMS
 109 ===========================
 110
 111 For those concerned about ultimate performance you may not wish to suffer the slight PHP and
 112 database overhead of the Contact Importer Form Integration module.  Instead you can bind Contact
 113 Importer directly to your form element.  Here's an example textarea that we are binding with
 114 Contact Importer.
 115
 116 <?php
 117
 118   $form['some_form_element'] = array(
 119     '#type' => 'textarea',
 120     '#title' => t('Enter the email addresses of friends you would like to invite to sign'),
 121     '#description' => t('List of email addresses separated by commas or new lines. '),
 122   );
 123
 124   // Add Contact Importer integration.
 125   if (module_exists('contact_importer')) {
 126     contact_importer_bind_to_form($form, 'some_form_element');
 127   }
 128
 129 ?>
 130
 131
 132 INTEGRATING WITH MORE SPECIFIC CUSTOMIZATION
 133 ============================================
 134
 135 If you require specific customizations you can imitate contact_importer_bind_to_form().  See the
 136 comments in that function for more details.
 137
 138 In some cases you may need more control over the emails being imported.  You can use
 139   hook_contact_importer_contacts_alter(&$list, $imported)
 140 to add extra functionality, such as saving all imported email addresses in another db table (for
 141 example).
 142
 143
 144 WRITING OTHER RETRIEVAL ENGINES
 145 ===============================
 146
 147 Simply copy and re-name the octazen_engine or openinviter_engine directory and files.  Then edit
 148 the files to work with the new retrieval service.  There are lots of in-line comments in the
 149 modules so it should be fairly straightforward.