modules/invite/README.txt

/* $Id: README.txt,v 1.14.2.1 2010/07/29 00:58:30 smk Exp $ */

-- SUMMARY --

Invitations are important to create network effects and exponential growth of a 
community of interest. This module adds an 'Invite a friend' feature that 
allows your users to send and track invitations to join your site.

For a full description visit the project page:
  http://drupal.org/project/invite
Bug reports, feature suggestions and latest developments:
  http://drupal.org/project/issues/invite


-- REQUIREMENTS --

* Token module http://drupal.org/project/token


-- INSTALLATION --

1. Copy the invite module to your modules directory and enable it on the Modules
   page (admin/build/modules).

2. Give some roles permission to send invites at the Access control page
   (admin/user/access). The following permissions can be controlled:

   administer invitations - Allows users to access the administrative overview
     and settings pages.

   send mass invitations - Allows users to send an invitation to multiple
     recipients (this was formerly a setting known as "limit per turn").

   track invitations - To give users access to the overview pages and
     associated actions (withdraw etc). Useful to hide overviews from anonymous
     users.

   withdraw accepted invitations - This will allow your users to delete
     accepted invitations. It will also delete all invitations from/to a user
     upon termination of its account. Disable it to prevent users from deleting
     their account to be re-invited. With the help of the Cancel User Accounts
     module it is possible to terminate user accounts by withdrawing an
     invitation.
 
   view invite statistics - Allows users to view invite statistics on their
     profile pages as well as view the Top inviters/User rank block.

   view own invite statistics - Same as above, but limits viewing statistics to
     the user's own profile.

3. Invite adds a new registration mode called 'New user registration by
   invitation only' to the User settings page (admin/user/settings), which
   allows you to maintain a semi-private site. You can enable it if you need it.

4. Configure the module at User management > Invite settings
   (admin/user/invite). For an explanation of the configuration settings see
   below.


-- CONFIGURATION --

--- General settings ---

* Target role
  Allows to specify the role invited users will be added to when they
  register, depending on the role of the inviting user. The default is
  'authenticated user'.

* Invitation expiry
  Specify how long sent invitations are valid (in days). After an invitation
  expires the registration link becomes invalid.

--- Role settings ---

* Target roles
  Allows to specify an additional role invited users will be added to when they
  register, depending on the role of the inviting user.

* Invitation limit
  Allows to limit the total number of invitations each role can send.

--- E-mail settings ---

* Subject
  The default subject of the invitation e-mail.

* Editable subject
  Whether the user should be able to customize the subject.

* Mail template
  The e-mail body.

* From e-mail address
  Choose whether to send the e-mail on behalf of the user or in the name of the
  site.

* Manually override From/Reply-To e-mail address (Advanced settings)
  Allows to override the sender and reply-to addresses used in all e-mails.
  Make sure the domain matches that of your SMTP server, or your e-mails will
  likely be marked as spam.


-- USAGE --

Sent invitations show up in one of three states accepted, pending, expired, or deleted.

* Accepted: Shows that the person you have invited has accepted the invitation
  to join the site.
* Pending: The invitation has been sent, but the invitee has since not accepted
  the invitation.
* Expired: The invitation has not been used to register within the expiration
  period.
* Deleted: The user account has been blocked.

At any time, pending or expired invitations may be withdrawn. Accepted
invitations may only be withdrawn if the configuration allows you to.


-- INVITE API --

The Invite module exposes hook_invite() that allows any module to react to the
invite lifecycle.

function hook_invite($op, $args) {
  case 'invite':
    An invitation has been successfully send.
    $args['inviter']: The user account object of the person who did the
                      inviting.
    $args['email']:   The e-mail address of the user who got invited.
    $args['code']:    The tracking code of the invitation.

  case 'escalate':
    Invitee has accepted an invitation and has been promoted to the appropriate
    user roles.
    $args['invitee']: The user account object of the person who was invited.
    $args['inviter']: The user account object of the person who did the
                      inviting.
    $args['roles']:   An array of roles the invited person has been escalated
                      to.
   
  case 'cancel':
    Inviter has cancelled an invitation.
    $args['inviter']: The user account object of the person who did the
                      inviting.
    $args['email']:   The e-mail address of the user whose invitation got
                      cancelled.
    $args['code']:    The tracking code of the invitation.
}


-- CREDITS --

Original author:
  David Hill (tatonca)

Current maintainer:
  Stefan M. Kudwien (smk-ka) - http://drupal.org/user/48898

1	/* $Id: README.txt,v 1.14.2.1 2010/07/29 00:58:30 smk Exp $ */
2
3	-- SUMMARY --
4
5	Invitations are important to create network effects and exponential growth of a
6	community of interest. This module adds an 'Invite a friend' feature that
7	allows your users to send and track invitations to join your site.
8
9	For a full description visit the project page:
10	http://drupal.org/project/invite
11	Bug reports, feature suggestions and latest developments:
12	http://drupal.org/project/issues/invite
13
14
15	-- REQUIREMENTS --
16
17	* Token module http://drupal.org/project/token
18
19
20	-- INSTALLATION --
21
22	1. Copy the invite module to your modules directory and enable it on the Modules
23	page (admin/build/modules).
24
25	2. Give some roles permission to send invites at the Access control page
26	(admin/user/access). The following permissions can be controlled:
27
28	administer invitations - Allows users to access the administrative overview
29	and settings pages.
30
31	send mass invitations - Allows users to send an invitation to multiple
32	recipients (this was formerly a setting known as "limit per turn").
33
34	track invitations - To give users access to the overview pages and
35	associated actions (withdraw etc). Useful to hide overviews from anonymous
36	users.
37
38	withdraw accepted invitations - This will allow your users to delete
39	accepted invitations. It will also delete all invitations from/to a user
40	upon termination of its account. Disable it to prevent users from deleting
41	their account to be re-invited. With the help of the Cancel User Accounts
42	module it is possible to terminate user accounts by withdrawing an
43	invitation.
44
45	view invite statistics - Allows users to view invite statistics on their
46	profile pages as well as view the Top inviters/User rank block.
47
48	view own invite statistics - Same as above, but limits viewing statistics to
49	the user's own profile.
50
51	3. Invite adds a new registration mode called 'New user registration by
52	invitation only' to the User settings page (admin/user/settings), which
53	allows you to maintain a semi-private site. You can enable it if you need it.
54
55	4. Configure the module at User management > Invite settings
56	(admin/user/invite). For an explanation of the configuration settings see
57	below.
58
59
60	-- CONFIGURATION --
61
62	--- General settings ---
63
64	* Target role
65	Allows to specify the role invited users will be added to when they
66	register, depending on the role of the inviting user. The default is
67	'authenticated user'.
68
69	* Invitation expiry
70	Specify how long sent invitations are valid (in days). After an invitation
71	expires the registration link becomes invalid.
72
73	--- Role settings ---
74
75	* Target roles
76	Allows to specify an additional role invited users will be added to when they
77	register, depending on the role of the inviting user.
78
79	* Invitation limit
80	Allows to limit the total number of invitations each role can send.
81
82	--- E-mail settings ---
83
84	* Subject
85	The default subject of the invitation e-mail.
86
87	* Editable subject
88	Whether the user should be able to customize the subject.
89
90	* Mail template
91	The e-mail body.
92
93	* From e-mail address
94	Choose whether to send the e-mail on behalf of the user or in the name of the
95	site.
96
97	* Manually override From/Reply-To e-mail address (Advanced settings)
98	Allows to override the sender and reply-to addresses used in all e-mails.
99	Make sure the domain matches that of your SMTP server, or your e-mails will
100	likely be marked as spam.
101
102
103	-- USAGE --
104
105	Sent invitations show up in one of three states accepted, pending, expired, or deleted.
106
107	* Accepted: Shows that the person you have invited has accepted the invitation
108	to join the site.
109	* Pending: The invitation has been sent, but the invitee has since not accepted
110	the invitation.
111	* Expired: The invitation has not been used to register within the expiration
112	period.
113	* Deleted: The user account has been blocked.
114
115	At any time, pending or expired invitations may be withdrawn. Accepted
116	invitations may only be withdrawn if the configuration allows you to.
117
118
119	-- INVITE API --
120
121	The Invite module exposes hook_invite() that allows any module to react to the
122	invite lifecycle.
123
124	function hook_invite($op, $args) {
125	case 'invite':
126	An invitation has been successfully send.
127	$args['inviter']: The user account object of the person who did the
128	inviting.
129	$args['email']: The e-mail address of the user who got invited.
130	$args['code']: The tracking code of the invitation.
131
132	case 'escalate':
133	Invitee has accepted an invitation and has been promoted to the appropriate
134	user roles.
135	$args['invitee']: The user account object of the person who was invited.
136	$args['inviter']: The user account object of the person who did the
137	inviting.
138	$args['roles']: An array of roles the invited person has been escalated
139	to.
140
141	case 'cancel':
142	Inviter has cancelled an invitation.
143	$args['inviter']: The user account object of the person who did the
144	inviting.
145	$args['email']: The e-mail address of the user whose invitation got
146	cancelled.
147	$args['code']: The tracking code of the invitation.
148	}
149
150
151	-- CREDITS --
152
153	Original author:
154	David Hill (tatonca)
155
156	Current maintainer:
157	Stefan M. Kudwien (smk-ka) - http://drupal.org/user/48898
158