modules/contact_importer/README.txt

$Id: README.txt,v 1.1.2.4.2.1 2009/06/29 14:57:06 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 at least one
   Retrieval Engine module.
3) Review the documentation link for the Retrieval Engine that you have chosen.
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 retrieval 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

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.


INTEGRATE WITH ANY FORM
=======================

1) Enable the Contact Importer Form Integration module
2) Enable Form ID and Field messaging at /admin/settings/contact_importer
3) Navigate to the page containing your form.  Note the Form ID and Field name that you want to use
   with Contact Importer.
4) Enter the Form ID and Field at /admin/settings/contact_importer/forms


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

For those concerned about ultimate performance you may not wish to suffer the slight PHP and
database overhead of the Contact Importer Form Integration module.  Instead you can bind Contact
Importer directly to your form element.  Here's an example textarea that we are binding with
Contact Importer.

<?php

  $form['some_form_element'] = 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. '),
  );

  // Add Contact Importer integration.
  if (module_exists('contact_importer')) {
    contact_importer_bind_to_form($form, 'some_form_element');
  }

?>

INTEGRATING WITH MORE SPECIFIC CUSTOMIZATION
============================================

If you require specific customizations you can imitate contact_importer_bind_to_form().  See the
comments in that function for more details.


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 or queuing mechanism in place so that if a user uses Contact Importer to insert
  500 email addresses into your textbox, your server 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.
1	$Id: README.txt,v 1.1.2.4.2.1 2009/06/29 14:57:06 dalin Exp $
2
3	CONTACT IMPORTER
4	================
5
6	Contact Importer provides a form for your users to enter their email address and password. The
7	contacts from their address book are then retreived.
8
9	On its own the module will only provide a method to retrieve the email addresses, but not actually
10	do anything with them. It provides a simple way to integrate with other modules so that it can
11	be used with an invite module, a user import module, an emailing module, your own custom forms,
12	or anything else that you can think of.
13
14	The initial release interfaces with the Octazen retrieval service, but the architecture is modular
15	and can be easily extended to use other retrieval services such as Contact Mines, ImproSys, IpInvite
16	or the open source but in need of an active maintainer Contact Grabber.
17
18	Developed By
19	------------
20
21	Advomatic LLC
22	http://advomatic.com
23
24	Sponsored By
25	------------
26
27	Democrats.com
28	http://democrats.com
29
30
31	INSTALLATION
32	============
33
34	1) Unpack the module into your sites/all/modules directory.
35	2) Go to Administer > Build > Modules . Enable the Contact Importer module and at least one
36	Retrieval Engine module.
37	3) Review the documentation link for the Retrieval Engine that you have chosen.
38	3) Enable permisions at Adminster > User > Access Control
39	3) Go to Administer > Configure > Contact Importer to setup the module.
40	4) Follow the links to go signup at one of the supported retrieval services.
41	5) Unpack the retrieval service library in the folder of the retrieval engine module.
42	6) Integrate Contact Importer into your forms.
43
44
45	OPTIONAL EXTRAS
46	===============
47
48	Contact Importer works best in conjunction with the Lightbox2 module.
49	http://drupal.org/project/lightbox2
50
51	Contact Importer will use Lightbox2 to show a modal pop-up so that the user can import from her
52	address book without leaving the current page. In the absence of Javascript, Contact Importer
53	degrades to a multistep-form-like method.
54
55
56	INTEGRATE WITH ANY FORM
57	=======================
58
59	1) Enable the Contact Importer Form Integration module
60	2) Enable Form ID and Field messaging at /admin/settings/contact_importer
61	3) Navigate to the page containing your form. Note the Form ID and Field name that you want to use
62	with Contact Importer.
63	4) Enter the Form ID and Field at /admin/settings/contact_importer/forms
64
65
66	INTEGRATING WITH YOUR FORMS
67	===========================
68
69	For those concerned about ultimate performance you may not wish to suffer the slight PHP and
70	database overhead of the Contact Importer Form Integration module. Instead you can bind Contact
71	Importer directly to your form element. Here's an example textarea that we are binding with
72	Contact Importer.
73
74	<?php
75
76	$form['some_form_element'] = array(
77	'#type' => 'textarea',
78	'#title' => t('Enter the email addresses of friends you would like to invite to sign'),
79	'#description' => t('List of email addresses separated by commas or new lines. '),
80	);
81
82	// Add Contact Importer integration.
83	if (module_exists('contact_importer')) {
84	contact_importer_bind_to_form($form, 'some_form_element');
85	}
86
87	?>
88
89	INTEGRATING WITH MORE SPECIFIC CUSTOMIZATION
90	============================================
91
92	If you require specific customizations you can imitate contact_importer_bind_to_form(). See the
93	comments in that function for more details.
94
95
96	CONSIDERATIONS
97	==============
98
99	It should be noted that using Contact Importer makes it very easy for your users to send email to
100	a lot of people. It is recommended that you:
101	- have a captcha or a simlar method in place to prevent spambots from using your form to send
102	spam.
103	- limit the number of emails/contacts that anonymous users can send/import.
104	- have a throttling or queuing mechanism in place so that if a user uses Contact Importer to insert
105	500 email addresses into your textbox, your server is not brought to its knees when the form is
106	submitted.
107
108
109	WRITING OTHER RETRIEVAL ENGINES
110	===============================
111
112	Simply copy and re-name the octazen_engine directory and files. Then edit the files to work with
113	the new retrieval service. There are lots of in-line comments in octazen_engine.module so it
114	should be fairly straightforward.