$Id: README.txt,v 1.1.2.4 2008/09/22 05:20:59 dalin Exp $

CONTACT IMPORTER
================

Contact Importer provides a form for your users to enter their email address and password. The 
contacts from their address book are then retreived. 

On its own the module will only provide a method to retrieve the email addresses, but not actually 
do anything with them. It provides a simple way to integrate with other modules so that it can 
be used with an invite module, a user import module, an emailing module, your own custom forms, 
or anything else that you can think of.  

The initial release interfaces with the Octazen retrieval service, but the architecture is modular 
and can be easily extended to use other retrieval services such as Contact Mines, ImproSys, IpInvite 
or the open source but in need of an active maintainer Contact Grabber. 

Developed By
------------

Advomatic LLC
http://advomatic.com

Sponsored By
------------

Democrats.com
http://democrats.com


INSTALLATION
============

1) Unpack the module into your sites/all/modules directory. 
2) Go to Administer > Build > Modules . Enable the Contact Importer module and atleast one 
   Retreival Engine module.
3) Enable permisions at Adminster > User > Access Control
3) Go to Administer > Configure > Contact Importer to setup the module.  
4) Follow the links to go signup at one of the supported retrieval services.  
5) Unpack the retrieval service library in the folder of the retreival engine module. 
6) Integrate Contact Importer into your forms.


OPTIONAL EXTRAS
===============

Contact Importer works best in conjunction with the Lightbox2 module. 
http://drupal.org/project/lightbox2
Lightbox2 requires the jQuery Update module.
http://drupal.org/project/jquery_update

Contact Importer will use Lightbox2 to show a modal pop-up so that the user can import from her 
address book without leaving the current page.  In the absence of Javascript, Contact Importer 
degrades to a multistep-form-like method. 


INTEGRATING WITH YOUR FORMS
===========================

Here's an example textarea that we are integrating with Contact Importer.

<?php

  $form['recipients'] = array(
    '#type'         => 'textarea',
    '#title'        => t('Enter the email addresses of friends you would like to invite to sign'),
    '#description'  => t('List of email addresses separated by commas or new lines. '),
    '#attributes'   => array(
      'class' => 'contact-importer-destination',
    ),
  );
    
  // Add Contact Importer integration.
  if (module_exists('contact_importer') && user_access('access contact importer')) {
    
    // If the user has already imported contacts, but they don't have Javascript, they will be 
    // redirected back here.
    $form['some_form_item']['#default_value'] = contact_importer_get_contacts();
    
    // Initiate Contact Importer.  
    // It is important that this happens after saved contacts are got above.
    contact_importer_add_js();
    
    // Show the link to import the contacts.
    $form['recipients']['#some_form_item'] .= '<div class="contact-importer-message">'. 
      t('You can also <a href=!importer-link class="contact-importer-link">import your '.
      'contacts from GMail, Yahoo!, Lycos, AOL, Hotmail and many more.</a>', 
      array('!importer-link' => url('contact_importer'))) .
      '</div>';
    
    // This message will be shown after the user has imported contacts.
    // The purpose is to remind the user to review the list so as to avoid spamming.
    $form['recipients']['#some_form_item'] .= '<div class="contact-importer-review-message" '.
      'style="display: none">'.
      t('Please review the list and delete those who would not be interested in this petition '.
      'before you submit the form.') .
      '</div>'; 
  }

?>

The important things are:
- contact-importer-destination class on your textfield / textarea.
- Check if a module exists before calling its functions.
- Check if the user has permission to 'access contact importer' before presenting the link to it. 
- contact-importer-link class on the Contact Importer link to get Lightbox2 integration.
- contact-importer-review-message class on the message that you want to show after the contacts 
  have been imported.  Hide the message initially, Contact importer will reveal it when the time 
  is right.

Here's an example of integrating Contact Importer with a pre-existing form (See this handbook page 
for information on how to write a custom module http://drupal.org/node/508).

<?php

function mymodule_form_alter($form_id, &$form) {
  if ($form_id == 'some_form') {
    
    // When Lightbox2 is used, this class tells Contact Importer to put the email addresses here.
    $form['some_form_item']['#attributes']['class'] .= ' contact-importer-destination';
    
    if (module_exists('contact_importer') && user_access('access contact importer')) {
      
      // If the user has already imported contacts, but they don't have Javascript, they will be 
      // redirected back here.
      $form['some_form_item']['#default_value'] = contact_importer_get_contacts();
      
      // Initiate Contact Importer.
      // It is important that this happens after saved contacts are got above.
      contact_importer_add_js();
      
      // Show the link to import the contacts.
      $form['some_form_item']['#description'] .= '<div class="contact-importer-message">'. 
        t('You can also <a href=!importer-link class="contact-importer-link">import your '.
        'contacts from GMail, Yahoo!, Lycos, AOL, Hotmail and many more.</a>', 
        array('!importer-link' => url('contact_importer'))) .
        '</div>';
      
      // This message will be shown after the user has imported contacts.
      // The purpose is to remind the user to review the list so as to avoid spamming.
      $form['some_form_item']['#description'] .= '<div class="contact-importer-review-message" '.
        'style="display: none">'.
        t('Please review the list and delete those who would not be interested in this petition '.
        'before you submit the form.') .
        '</div>'; 
    }
  }
}

?>

CONSIDERATIONS
==============

It should be noted that using Contact Importer makes it very easy for your users to send email to 
a lot of people.  It is recommended that you:
- have a captcha or a simlar method in place to prevent spambots from using your form to send 
  spam. 
- limit the number of emails/contacts that anonymous users can send/import.
- have a throttling mechanism in place so that if a user uses Contact Importer to insert 500 email
  addresses into your textbox, your whole system is not brought to its knees when the form is 
  submitted. 


WRITING OTHER RETRIEVAL ENGINES
===============================

Simply copy and re-name the octazen_engine directory and files.  Then edit the files to work with 
the new retrieval service.  There are lots of in-line comments in octazen_engine.module so it 
should be fairly straightforward. 
