Invitations
Building closed community with ExpressionEngine has just become easier! Generate signup codes from CP, or let people generate them on frontend. View usage stats, associate users with people they invited, - and event let them earn credits for bringing referrals.
↑ General concepts
There are several potentional areas of use for invitations on your site:
- Build a closed community. Only people who have invitation code can sign up
- Advanced group management. People can move themseleves to membes group with special privileges by applying invitation code (when they sign up or afterwards)
- Build affiliate system. Let your users generate codes to invite others and track when they are used.
- Add bonus to user's account when code is used (both to the one who generated and who uses code). This feature requires Credits module from DevDemon.
↑Using invitation
↑Using invitation during signup
To let people apply invitation code during signup, simply add input field named "invitation" to registration form.
<br /><input type="text" name="invitation" value="" />
↑Applying invitation by existing user
You can also let existing users apply invitation codes to their account. Please refer to tags reference.
↑Control Panel
↑Settings
If you have MSM installed, setting are saved separately for each site.
The available settings for Invitations module are:
Invitation is required? - mark the checkbox if the users can sign up only of they know invitation code
Freeform from that requires valid invitation - if checked, given forms created using Freeform module can be submitted only if "invitation" field is submitted and contains valid code
Default members group to assign - if you want to use separate membership group for people who sign up using invitation, you can define default one here (can be overridden during code generation)
Default credits for invitation author - define the amount of credits that will be added to author's account when invitation is used (requires Credits module)
Default credits for invitation user - define the amount of credits that will be added to user's account when invitation is used (requires Credits module)
↑Invitations list
The homepage of module's Control Panel shows list of all invitations available for your site(s). You can filter to show all/expired/used/available and also define how many you want to show per page.
You can also change sorting order by clicking on head for the column you want to sort by (on-page sorting only, does not influence results on other pages, if you have paginations)
↑Invite usage stats
You can access invite details by clicking stats icon from invitations list. You will see the full details for selected code as well as when it has been used and by whom. If the date of usage is not shown, it means that the user has not yet completed the registration (or not approved yet).
↑Generating invitation code
Click "Generate" button at the right top to create new invite code.
Enter any word to be used as code, or click '(Generate)' to get an authomatic one. You can also leave the field empty to use authomatic value.
Define membership group to be assigned after registration is complete.
If you want to restrict invite code to be used only with certain email address (i.e. only by certain person), enter that email into Restrict to email address field.
Set number of times the code can be used (defaults to one time) or mark checkbox to use no limit.
You can also optionally set the date when the code will expire and can not be used anymore.
If you have Credits module installed, you can also set Credits for invitation author and user. The amounts will be added after invitation code is used (by new or existing user). For new user, the credit is applies only after the registration is complete (email address validated, or manually validated by admin - if you use that kind of validation). For existing users, the code can be used (and credit is applied) only if code usage will result in change of membership group.
↑Batch code generation
You can generate several codes at once by clicking 'Batch Generate'. All fields are the same, except that you are forced to use auto-generated values for invitation codes. You'll also be asked about number of invites you want (defaults to 5).
↑Template tags
↑Generate invitation code
You can let your existing users invite other people by generating invitation codes. Outputs the invite code that can be passed to other people. You need to perform your own checks on who's allowed to generate invitations.
All codes generated on frontend can be used just once.
Simple example
{exp:invitations:generate}
Advanced example
{exp:invitations:generate email="my-friend@domain.com" destination_group_id="8" credits_author="5" credits_user="1" expire_in="10 days"}
Parameters (all optional):
- email — specify invitee email address if you want to restrict usage of this code to this email owner only
- destination_group_id — member's group ID to assign (overrides default value)
- credits_author — amount of credits to be added to account of member who generated code
- credits_user — amount of credits to be added to account of member who used code
- expire_in — define after what time the code will be considered as expired. The value of this parameter is English phrase, e.g. expire_in="5 days", expire_in="2 month" etc.
- expire_on — set on what time exactly the invitation will expire. The value of this parameter is date and time in format 2012-01-28 3:16 PM
↑Display invitations
This tags allows you display all invitations ever generated, or invitations that still can be used, or invitations by currently logged in user.
{exp:invitations:display mode="all" paginate="both" limit="10"}
{paginate}{pagination_links}{/paginate}
<p>{count}. <strong>{code}</strong>
{if valid}
Can be used {use_left} times
{/if}
{if not_valid}
Can not be used anymore
{/if}
{if used}
Used by:
{users backspace="1"}
<a href="{path=member/profile/{user_id}}">{user_screen_name}</a>,
{/users}
{/if}
<p>
{/exp:invitations:display}
Tag parameters(all optional):
- mode — set to show all invitations (mode="all"), valid only (mode="valid") or only generated by logged in user (mode="my")
- limit — number of codes per page, if you want to use pagination
- paginate — place to display pagination links. Can be 'top', 'bottom' or 'both'. Defaults to 'bottom'
- backspace="X" — remove X last characters from tag output result
Conditional variables:
- {if no_results}{/if} — displayed if there are no codes to show
- {if valid}{/if} — displayed if invitation is valid and can be used
- {if not_valid}{/if} — displayed if invitation is not valid and can not be used (expired or reached usage limit)
- {if expired}{/if} — displayed if the code has expired
- {if used}{/if} — displayed if the code has been used at least one time
Single variables:
- total_results — total number of invitations in provided mode
- count — invites counter on each page
- absolute_count — invites counter throughout all pages
- code — the actual invitation code string
- author_id — member ID of person who created this invitation
- author_username — username of person who created this invitation
- author_screen_name — screen name of person who created this invitation
- destination_group_id — membership group that will be assigned to user of this code
- restricted_email — if the code is restricted to be used with certain email address, shows this address
- credits_author — amount of credits for code author (using Credits module)
- credits_user — amount of credits for code user (using Credits module)
- use_count — number of times the code has been used
- use_left — number of times the code still can be used (if no limit, shows the word 'unlimited')
- created_date format="%Y-%m-%d" — the date when code has been created. Standard EE date formatting rules apply.
- expires_date format="%Y-%m-%d" — the date when code expires. Standard EE date formatting rules apply.
Variable pairs:
{users backspace="X"}{/users} — display list of members who used this code.
- user_id — user's member ID
- user_username — user's username
- user_screen_name — user's screen name
- used_date format="%Y-%m-%d" — the date when invitations was used. Standard EE date formatting rules apply.
{paginate}{/paginate} — used to format and display pagination links (if you have limit parameter set and there's more than one page)
- pagination_links — the actual pagination links
↑Applying invitation by existing user
You can also let your existing users apply invitation (consider is as promo code) to be authomatically moved to destination group.
{exp:invitations:apply return="SAME_PAGE"}
<p>Got promo code? Apply it here:</p>
<p><input name="invitation" value="" /></p>
<p><input type="submit" value="Apply" /></p>
{/exp:invitations:apply}
Tag parameters:
- return — a page to return after sending message. Can be a full URL or URI segments.
Use return="SAME_PAGE" to return user to the page used to display form. - id — form ID (defaults to 'invitations_form')
- class — form class (defaults to 'invitations_form')
- name — form name (defaults to 'invitations_form')
Form fields:
- invitation — input for invitation/promo code
↑Referrals
It's possible to list referrals for your site member(s), i.e. people who registered using invitation code generated by that person.
<p>My referrals</p>
{exp:invitations:referrals}
<p><a href="{path=member/profile/{member_id}}">{screen_name}</a>,</p>
{/exp:invitations:referrals}
Tag parameters:
- member_id — ID of member for whom we want to display referrals. Defaults to logged in member.
- backspace="X" — remove X last characters from tag output result
Single variables:
- total_results — total number of referrals for give member
- member_id — referral's member ID
- username — referral's username
- screen_name — referral's screen name
- group_id — referral's membership group
↑Referrer
You can also display who has referred current (or any) user to the site (i.e. who generated the code he used)
{exp:invitations:referrer}
<p>I've been referred by <a href="{path=member/profile/{member_id}}">{screen_name}</a></p>
{if no_results}<p>I've found this place myself</p>{/if}
{/exp:invitations:referrer}
Tag parameters:
- member_id — ID of member for whom we want to display referrals. Defaults to logged in member.
Single variables:
- member_id — referrer's member ID
- username — referrer's username
- screen_name — referrer's screen name
- group_id — referrer's membership group