modules/invite/README.txt

/* $Id: README.txt,v 1.4.2.17.2.3 2008/07/12 21:40:13 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:

   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 --

To invite a friend :

1. Click the 'Invite your friends and colleages' link.
3. Fill in the e-mail address(es) of the person(s) you would like to invite,
   and add a personal message.
4. Press submit.
5. This will send an invitation e-mail which you can now track from the
   'Your invitations' page.

Invitations show up in one of the states accepted, pending, expired, and the
special case deleted.

* Accepted: Shows that the person you have invited has accepted the invitation
  to join the site. Click on the e-mail address to watch the user's profile
  page.
* Pending: The invitation has been sent, but the invitee has still not accepted
  the invitation.
* Expired: The invitation has not been used to register within the expiration
  period.
* Deleted: The user account has been terminated.

At any time, you may withdraw either pending or expired invitations.
Accepted invitations can 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.
}

There are several third-party modules that can react on invite events:

* Buddylist http://drupal.org/project/buddylist
  User Relationships http://drupal.org/project/user_relationships
  Inviter and invitee are automagically put on their respective buddy list.

* Userpoints http://drupal.org/project/userpoints
  Credit some points for sending registrations and/or when an invited user
  registers.


-- TROUBLESHOOTING --

When the site is set to allow new accounts by invitation only, it would be nice 
to remove the 'Create new account' tab that shows up if a user clicks on the 
'Request a new password' link. There seems no way to remove existing menu 
entries.

To solve this issue, you could add the following function to your template.php:

function phptemplate_menu_item_link($item, $link_item) {
  if ($link_item['path'] == 'user/register') return;
  return l($item['title'], $link_item['path'], !empty($item['description']) ? array('title' => $item['description']) : array(), isset($item['query']) ? $item['query'] : NULL);
}

This prevents the 'Create new account' menu item from being rendered.


-- CREDITS --

Original author:
  David Hill (tatonca)

Current maintainer:
  Stefan M. Kudwien (smk-ka)

Sponsored by UNLEASHED MIND
  Specialized in consulting and planning of Drupal powered sites, UNLEASHED
  MIND offers installation, development, theming, customization, and hosting
  to get you started. Visit http://www.unleashedmind.com for more information.

1	/* $Id: README.txt,v 1.4.2.17.2.3 2008/07/12 21:40:13 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	send mass invitations - Allows users to send an invitation to multiple
29	recipients (this was formerly a setting known as "limit per turn").
30
31	track invitations - To give users access to the overview pages and
32	associated actions (withdraw etc). Useful to hide overviews from anonymous
33	users.
34
35	withdraw accepted invitations - This will allow your users to delete
36	accepted invitations. It will also delete all invitations from/to a user
37	upon termination of its account. Disable it to prevent users from deleting
38	their account to be re-invited. With the help of the Cancel User Accounts
39	module it is possible to terminate user accounts by withdrawing an
40	invitation.
41
42	view invite statistics - Allows users to view invite statistics on their
43	profile pages as well as view the Top inviters/User rank block.
44
45	view own invite statistics - Same as above, but limits viewing statistics to
46	the user's own profile.
47
48	3. Invite adds a new registration mode called 'New user registration by
49	invitation only' to the User settings page (admin/user/settings), which
50	allows you to maintain a semi-private site. You can enable it if you need it.
51
52	4. Configure the module at User management > Invite settings
53	(admin/user/invite). For an explanation of the configuration settings see
54	below.
55
56
57	-- CONFIGURATION --
58
59	--- General settings ---
60
61	* Target role
62	Allows to specify the role invited users will be added to when they
63	register, depending on the role of the inviting user. The default is
64	'authenticated user'.
65
66	* Invitation expiry
67	Specify how long sent invitations are valid (in days). After an invitation
68	expires the registration link becomes invalid.
69
70	--- Role settings ---
71
72	* Target roles
73	Allows to specify an additional role invited users will be added to when they
74	register, depending on the role of the inviting user.
75
76	* Invitation limit
77	Allows to limit the total number of invitations each role can send.
78
79	--- E-mail settings ---
80
81	* Subject
82	The default subject of the invitation e-mail.
83
84	* Editable subject
85	Whether the user should be able to customize the subject.
86
87	* Mail template
88	The e-mail body.
89
90	* From e-mail address
91	Choose whether to send the e-mail on behalf of the user or in the name of the
92	site.
93
94	* Manually override From/Reply-To e-mail address (Advanced settings)
95	Allows to override the sender and reply-to addresses used in all e-mails.
96	Make sure the domain matches that of your SMTP server, or your e-mails will
97	likely be marked as spam.
98
99
100	-- USAGE --
101
102	To invite a friend :
103
104	1. Click the 'Invite your friends and colleages' link.
105	3. Fill in the e-mail address(es) of the person(s) you would like to invite,
106	and add a personal message.
107	4. Press submit.
108	5. This will send an invitation e-mail which you can now track from the
109	'Your invitations' page.
110
111	Invitations show up in one of the states accepted, pending, expired, and the
112	special case deleted.
113
114	* Accepted: Shows that the person you have invited has accepted the invitation
115	to join the site. Click on the e-mail address to watch the user's profile
116	page.
117	* Pending: The invitation has been sent, but the invitee has still not accepted
118	the invitation.
119	* Expired: The invitation has not been used to register within the expiration
120	period.
121	* Deleted: The user account has been terminated.
122
123	At any time, you may withdraw either pending or expired invitations.
124	Accepted invitations can only be withdrawn if the configuration allows you to.
125
126
127	-- INVITE API --
128
129	The Invite module exposes hook_invite() that allows any module to react to the
130	invite lifecycle.
131
132	function hook_invite($op, $args) {
133	case 'invite':
134	An invitation has been successfully send.
135	$args['inviter']: The user account object of the person who did the
136	inviting.
137	$args['email']: The e-mail address of the user who got invited.
138	$args['code']: The tracking code of the invitation.
139
140	case 'escalate':
141	Invitee has accepted an invitation and has been promoted to the appropriate
142	user roles.
143	$args['invitee']: The user account object of the person who was invited.
144	$args['inviter']: The user account object of the person who did the
145	inviting.
146	$args['roles']: An array of roles the invited person has been escalated
147	to.
148
149	case 'cancel':
150	Inviter has cancelled an invitation.
151	$args['inviter']: The user account object of the person who did the
152	inviting.
153	$args['email']: The e-mail address of the user whose invitation got
154	cancelled.
155	$args['code']: The tracking code of the invitation.
156	}
157
158	There are several third-party modules that can react on invite events:
159
160	* Buddylist http://drupal.org/project/buddylist
161	User Relationships http://drupal.org/project/user_relationships
162	Inviter and invitee are automagically put on their respective buddy list.
163
164	* Userpoints http://drupal.org/project/userpoints
165	Credit some points for sending registrations and/or when an invited user
166	registers.
167
168
169	-- TROUBLESHOOTING --
170
171	When the site is set to allow new accounts by invitation only, it would be nice
172	to remove the 'Create new account' tab that shows up if a user clicks on the
173	'Request a new password' link. There seems no way to remove existing menu
174	entries.
175
176	To solve this issue, you could add the following function to your template.php:
177
178	function phptemplate_menu_item_link($item, $link_item) {
179	if ($link_item['path'] == 'user/register') return;
180	return l($item['title'], $link_item['path'], !empty($item['description']) ? array('title' => $item['description']) : array(), isset($item['query']) ? $item['query'] : NULL);
181	}
182
183	This prevents the 'Create new account' menu item from being rendered.
184
185
186	-- CREDITS --
187
188	Original author:
189	David Hill (tatonca)
190
191	Current maintainer:
192	Stefan M. Kudwien (smk-ka)
193
194	Sponsored by UNLEASHED MIND
195	Specialized in consulting and planning of Drupal powered sites, UNLEASHED
196	MIND offers installation, development, theming, customization, and hosting
197	to get you started. Visit http://www.unleashedmind.com for more information.
198