README.txt in Invite 5

-- 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 5.x-1.9 (or newer)
  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['code']:    The invite code for the invitee.

  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 that the invitee 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.
}

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.


-- CONTACT --

Current maintainer:
Stefan Kudwien (smk-ka) - dev@unleashedmind.com

Original author:
David Hill (tatonca) - tatonca_@hotmail.com