Getting Started with the Nice Memberships Extension
Getting Started - Installation
Getting Started – Your PayPal Settings
Getting Started – Set Up PayPal Auto Return
Getting Started – Settings & Configuration
Getting Started – Your First Listing
The Nice Memberships Component
Automatic Account Creation
Membership Subscription at Registration
Nice Membership Button Tags
Membership Subscription Items
Message Profiles
Component Settings
The Nice Membership Plugins
Nice Membership Button Plugin
Nice Membership Expiry Plugin
Nice Membership Redirect Plugin
Nice Membership Profile Plugin
Getting Started
Getting Started - Installation
1. If you don't already have one, get a Business PayPal account now.
2. Install the extension using Joomla's Extension Manager: http://docs.joomla.org/Installing_an_extension
3. During the installation, 1 component and 4 plugins will be installed on your Joomla system. The component and 2 of the plugins are required for the proper operation of the Nice Memberships system. The other 2 plugins add optional features and may be excluded from your site, if you so choose.
Component: Nice Memberships (required)
The Nice Membership component is the core membership management system. It is required for proper operations of the extension.
Plugin: System - Nice Membership Button (required)
The Nice Membership Button plugin creates all subscribe and unsubscribe buttons on your site. It is required in order for the extension to function properly.
Plugin: System - Nice Membership Expiry (required)
The Nice Membership Expiry manages the expiration of memberships that have been canceled or have reached their end of term. This plugin is required in order for the extension to work properly.
Plugin: System - Nice Membership Profile (optional)
The Nice Membership Profile is responsible for displaying membership information on Joomla's user profile page. This plugin is optional. Without it the extension will work correctly, but the user will not have access to their membership information on their profile page.
Plugin: System - Nice Membership Redirect (optional)
The Nice Membership Redirect plugin redirects users to a pre-specified page, when the user logs in. This plugin is not required for the extension to work properly. However, this extension is needed if you plan to request that users subscribe to a membership during the registration process.
4. The 2 required plugins will need to be enabled. To enable the plugins go to Extensions>>Extension Manager and find System - Nice Membership Button & System - Nice Membership Expiry. Enable both of these plugins. You may like to enable to 2 optional plugins at this time as well.
^top
Getting Started – Your PayPal Settings
Your PayPal Account will also need a few quick changes in order to ensure that it is set up properly to handle IPN communications with the Nice Memberships extension.
1. Navigate to PayPal and login to your account
2. Go to Profile>>More Options>>My Selling Tools
3. Find "Instant Payment Notification" below the subtitle "Getting paid and managing my risk" and click the "update" link to the right.
4. Enter the Notification URL for the Nice PayPal Downloads extension. The URL is as follows (replace “yourdomain.com” with your website's domain name):
http://yourdomain.com/index.php?option=com_nicememberships&controller=Ipn&task=ipn
If you already have a URL in set as you Notification URL, don't worry. The Nice Memberships sends an override URL to PayPal during the purchase transaction. The important thing is that Instant Payment Notification is enabled in your PayPal Profile.
5. Tick the radio button labeled Receive IPN Notification and click Save.
Getting Started – Set Up PayPal Auto Return
Optionally, you may like to have your buyers automatically returned to the Nice Memberships return message page on your site. To do this simply follow the next few sub-steps below.
1. Login to PayPal
2. Go to My Account>>Profile>>More Options>>Website Payment Preferences
3. Select the Auto Return "on" radio button.
4. Enter your domain (http://www.yourdomain.com) in the Return URL field. This is a default, the Nice Memberships will send an override URL that returns the buyer to the Nice Membership's return message page.
5. Click the save button.
If you don't set up auto return the buyer will be presented with a button on the PayPal site that, when clicked, returns them to your site.
Getting Started – Settings & Configuration
The Nice Memberships extension is designed for to maximize configuration options and flexibility in implementation. Most of the settings have been pre-configured and there is very little that you will need to alter to get up and running successfully.
You do need to add your PayPal seller's primary email address to the component settings.
1. Go to Components>>Nice Memberships>>Settings
2. Enter your PayPal seller's primary email address in the field labeled “PayPal Account Email”
3. Click the Save button.
4. Now go to Components>>Nice Memberships>>Message Profiles>>Default Profiles
5. Enter your email address in the form field labelled "From Email Address."
6. Click the Save button.
That's it for basic settings. All other settings are pre-configured. After you have explored the extension, you may choose to learn more about the various settings. The other settings are covered in more depth, later in this documentation.
Getting Started – Your First Listing
During the installation of the extension a sample membership item & message profile is created. It would be advantageous for you to review these two samples to obtain a better understanding of how to set up a membership item for sale. To review the sample membership item go to Administrator>>Components>>Nice Memberships and click on Test Membership in the item list. To review the sample message profile go to Administrator>>Components>>Nice Memberships>>Message Profiles and click on Default Profile.
It is important to understand that each membership item listings consists of two parts. Theses parts are the membership item listing itself and a message profile. The membership item stores all of the item related data. The message profile contains all of the messages (related to the membership item) needed to communicate with the buyer. In this way, you can use one message profile for all of your membership items or use an individual message profile for an individual membership item.
Now, lets get on with your first listing. We are going to use the sample item “Test Membership” that was already set up during the installation. It uses the “Default Profile” for all of its messaging. There are three different ways that this listing can be shown to the potential buyer.
The first method is perhaps the easiest. Simply go to http://yourdomain.com/index.php?option=com_nicememberships and you should see a list of available memberships offered by your site. Voila! your first listing is complete! This method works well when the Nice Membership Redirect is enabled, as the user will be automatically sent to the membership list page, by the Redirect plugin, when they log in.
The second method is almost as simple. This method requires that the potential buyer be already registered with your website. When the potential buyer logs into your site and views their user profile, they will see a list of available memberships appended to their profile page information. The Nice Membership Profile plugin needs to be enabled for this method.
The third method for displaying a membership item to your potential buyers is by far the most flexible and allows you to place the membership item information and subscription button almost anywhere on your site. Simply add/type a button tag into any Joomla article, custom module etc. The tag will be replaced, on the front end, by a PayPal subscription button.
The basic button tag has a very simple syntax.
Syntax
{nicememberships:item_id}
Example
{nicememberships:1}
In the example above, we have specified 1 as the item number. If you go to Administrator>>Components>>Nice Memberships you will notice that 1 is the id number (far left hand column) of our Test Membership item. All membership items will have a id number in the left hand column. This is the number you use in the button tag.
*Please note that when a buyer subscribes to a membership, the extension will only ADD user group access to the user's account. It will not subtract user group access (unless the membership is canceled or expires).
The Nice Memberships Component
Automatic Account Creation
The Nice Memberships extension is equipped to handle the creation of user accounts for buyers who are not registered with your website prior to purchasing a membership. This is a very handy feature and provides a lot flexibility in the deployment of the extension.
When a buyer, who is not registered with your site, purchases a membership, the extension will automatically create a new account for the buyer. The extension uses the buyer's PayPal email account as the username. The extension will also randomly generate a password for the buyer. After which, the an email is sent to the buyer's paypal email address with their new account's username and password.
If the buyer already has a registered account with your site, the extension will attempt to identify the buyer and add the membership to their existing account. Registered accounts are identified in several ways.
First, if the buyer is logged into your site when they click the purchase button, then the buyer's user id is used to identify them. If the buyer is not logged in to your site, the extension will try to match the buyer's PayPal email address to an existing user in your Joomla site's registered user base.
Membership Subscription at Registration
The Nice Membership extension allows for user's to subscribe to memberships during your site's registration process. During the account sign-up process, the user registers in the normal way using Joomla's core account registration. Third party registration extensions can be used for account registration as well, as long as the user's new account information is submitted to Joomla's core user management system.
Once the user has confirmed their email address and their account has been approved, they will log into their account for the first time. At this point the user does not have a Membership and will be automatically redirected to the Nice Memberships' membership purchase list.
This method is used to avoid the need to hack or replace the existing Joomla core registration process. If set up correctly the membership subscription experience should appear to be seamless to the end user.
Here is how it works.
1. The visitor registers with your site using Joomla's core registration process.
2. Your Joomla site processes the user registration, adds the user to the base registration user group, and sends them an email with their login information.
3. When the user logs into your site, they are automatically redirected to http://yourdomain.com/index.php?option=com_nicememberships where they are prompted to subscribe to a membership.
4. The user selects a membership by clicking on the subscribe button.
5. They are taken to PayPal to complete the subscription purchase process.
6. Upon a successful transaction with PayPal, they are returned to your site and are shown a "Thank You" message.
7. The user's account is automatically added to the user groups specified by the membership item.
8. The user now has new site permissions granted by their addition to the new user groups.
To utilize this configuration with your site, you will need to ensure that the Nice Membership Redirect plugin is enabled. Go to Administrator>>Extensions>>Plugin Manager>>System - Nice Membership Redirect and enable it.
The default behavior of the Nice Membership Redirect is to redirect a any user who does not have a membership subscription to the Nice Memberships component's default page. Both the redirect URL and the criteria (users without memberships) can be changed in the Nice Membership Redirect plugin's parameter settings.
Best Practice
When using this method for user registration and membership subscription, the best practice is to use at least 2 registered user groups. The first group should be your base registration user group. This is the group that all new account registrants are automatically added to upon the creation of a new account. By default the base user group in Joomla is "Registered." When a user creates a new account they are automatically added to the user group called "Registered." The default base user group can be altered in the Joomla Global Configuration settings.
For this subscription sign-up method, your base user group should not have any extra permissions than the "Public" user group, other than being able to log in.
The second user group should be your Membership Item Group. You will need to create a new custom user group for this part. This group needs to have its permissions set to allow users (in the group) to be able to view your premium site content or premium site features, offered by the membership. When the registered user makes a membership purchase, they will be added to this group.
For more information on working with Joomla custom user groups and permissions check here:
Video: Joomla! 1.6 Quick Look: User Groups
http://people.joomla.org/videos/video/249-joomla-16-quick-look-user-groups.html?groupid=458
How permissions work in Joomla! 1.6
http://docs.joomla.org/ACL_Tutorial_for_Joomla_1.6#Users.2C_Groups.2C_and_Access_Levels
Nice Membership Button Tags
Nice Membership button tags make it possible to place a subscription button into an article, custom module, template or just about anywhere in a layout where text can be displayed to your site visitor. The button tag syntax is very straight forward.
Syntax
{nicememberships:item_id|custom_button_graphic_url}
Examples
{nicememberships:2}
{nicememberships:2|http://yourdomain.com/images/customgraphic.jpg}
In the tag above you will see that there are two parameters that can be specified. These parameters are item_id and custom_button_graphic_url. The item_id is a required parameter, while the custom_button_graphic_url is optional.
To determine the the item_id go to Administrator>>Components>>Nice Memberships. In the farthest left column of the items list, you will see the column labelled “ID.” Each id number in the column corresponds to the item on the same row. Use this id number to as the item_id in the button tag.
If you would like to use a custom graphic for your button, instead of PayPal's default subscription button, then input the custom graphics URL as the custom_button_graphic_url.
You can also specify that you would like an unsubscribe button to added to your layout by using the following tag.
{nicememberships:unsubscribe}
You can specify a custom unsubscribe button graphic in the same way as a subscription button.
Example
{nicememberships:unsubscribe|http://yourdomain.com/images/scustomunsubscribe.jpg}
Membership Subscription Items
The Membership Subscription items are found at Administrator>>Components>>Nice Memberships. Each membership subscription item contains a large array of options and settings. This gives the administrator significant control over how the membership is to be set up.
Item Name
The name of the membership item
Show Item Name
If checked the item name will be displayed above the subscription button.
Item Description
A short description of the membership item
Show Item Description
If checked the item description will be displayed above the subscription button.
Trial Period 1 (optional)
If you want to offer a trial period you set the terms for it here. Please note that Trial Period 1 must be set, if Trial Period 2 is set.
Price
Enter the price of Trial Period 1. Enter 0.00 to offer Trial Period 1 for free. Do not use a currency symbol.
Number of Units
Number of time units for Trial Period 1. Example "2" Days, "2" would be the number of time units. Days allowed 1-90, Weeks allowed 1-52, Months allowed 1-24, Years allowed 1-5.
Units of Time
Select the units of time that you would like to use for Trial Period 1.
Trial Period 2 (optional)
If you want to offer a second trial period you set the terms for it here. Please note that Trial Period 2 can be empty, when Trial Period 1 is set.
Price
Enter the price of Trial Period 2. Enter 0.00 to offer Trial Period 2 for free. Do not use a currency symbol.
Number of Units
Number of time units for Trial Period 2. Example "2" Days, "2" would be the number of time units. Days allowed 1-90, Weeks allowed 1-52, Months allowed 1-24, Years allowed 1-5.
Units of Time
Select the units of time that you would like to use for Trial Period 2.
Regular Period
A Regular Period is required. The regular period is the primary membership subscription.
Price
Enter the price of the Regular Period. You cannot offer the Regular Period for free. Do not use a currency symbol.
Number of Units
Number of time units for the Regular Period. Example "2" Days, "2" would be the number of time units. Days allowed 1-90, Weeks allowed 1-52, Months allowed 1-24, Years allowed 1-5.
Units of Time
Select the units of time that you would like to use for the Regular Period.
Subscription
The subscription settings allow you to define what is offered with the membership and how the subscriber is billed.
Recurring Payments
Check this box if your membership is to automatically repeat every x number of Regular Periods. If this box is checked the buyer will be automatically billed at the beginning of every new Regular Period. If this box is unchecked the membership will only be active for one Regular period.
Number of Recurring Periods (optional)
Number of Recurring Periods must be empty or greater than 2. Leave Number of Recurring Periods empty for infinite recurring payments.
Allowed Modification
Select the terms for subscription modification. Allowed Modification must be set to Allow New Only if a Trial Period is set. This is unless, the subscription that the existing member holds has a trial period as well.
Allow New Subscriptions Only = Only new subscriptions will be created, with PayPal, for the buyer.
Allow New and Modify Existing Subscriptions = New subscriptions will be created, with PayPal, for the buyer. If the buyer has an existing subscription with your site, they will be allowed to modify it with this items terms.
Modify Existing Subscriptions Only = Only if the buyer has an existing subscription will they be allowed to subscribe to this item, by modifying their existing subscription with this items terms.
Subscribes to Groups
Select which groups will be added to the buyer's user account after purchase. Even if set in Subscribes to Groups, as a security measure Super User accounts can never be sold.
Messaging Profile
Select which Messaging Profile will be used with this membership.
Extended Options
To limit which user groups are allowed to see the subscription button, tick the Show to Specific Groups checkbox and select the Specific Groups that are allowed to see the subscription button. Please note, Super Users will always be allowed to see the subscription button.
Show to Specific Groups (optional)
Tick this to limit the display of the membership subscription button to specific user groups.
Specific Groups
Select the user groups for which the memebership subscription button will be displayed. This selection is only effective if the Show to Specific Groups option is enabled.
Message Profiles
Messaging profiles allow you to set various boilerplate page messages and email messages for the buyer. You can create multiple Message Profiles and use them for different membership items or use the same profile for multiple membership items.
Profile Name
Enter the name you wish to give your profile.
Return Message
This is the "Thank You" message the buyer will see when they return to your site, after a successful transaction with PayPal.
Cancellation Message
This is the message the buyer will see when they return from PayPal, after they have cancelled their transaction be for they complete the purchase.
From Email Address
Set your desired "From" email address here. It is advisable to use the same email address that is set in your Joomla Global Configuration.
Sign-up Email Subject
This is the email subject line used for the Sign-up email.
Sign-up Email message
The sign-up email is sent to users who have newly subscribed to a membership.
*IMPORTANT: If you plan to allow auto-account creation, then you need to include the following tokens in your email.
%username%
%password%
The two tokens will be replaced with the the new account's username and password. It is important to understand that including %password% is the only way that the user will be able to retrieve their new accout's password.
Modified Email Message Subject
This is the email subject line used for the Modified email.
Modified Email Message
The modified email is sent out when the a subscription has been modified.
Cancellation Email Subject
This is the email subject line used for the Cancellation email.
Cancelled Email Message
The cancellation email is sent out when the subscriber or seller cancels a current subscription through PayPal.
End of Term Email Subject
This is the email subject line used for the End of Term email.
End of Term Email Message
This is the email that is sent out when the subscriber's membership has reach the end of its term.
Failed Payment Email Subject
This is the email subject line used for the Failed Payment email.
Failed Payment Email Message
This email is sent out when a subscriber's automatic payment fails.
Component Settings
The component has a number of settings that can be altered by you to effect the manor in which the component behaves. The most important setting is the “PayPal Account Email”, which should now have your PayPal seller's primary email address in it. To access the component's settings page go to Administrator>> Components>>Nice Memberships>>Settings
PayPal Details
The first section of settings is the PayPal Details section
PayPal Account Email
Enter the primary email address associated with your PayPal seller.
PayPal Test Mode Email
This is an optional setting. If you plan to use the PayPal sandbox for testing purposes, you will need to enter your PayPal sandbox seller's email address here. Leave this field blank when you are not testing, or if you do not plan to use the sandbox.
PayPal Currency Code
Enter the PayPal currency code that you wish to use when selling your memberships. By default the currency code is set to USD. Check here for a list PayPal supported currency codes https://cms.paypal.com/us/cgi-bin/?cmd=_render-content&content_ID=developer/e_howto_api_nvp_currency_codes
PayPal Country Code
PayPal country codes dictate what language will be used on the PayPal checkout page. By default the country code is set to US. For a list of PayPal supported country codes check here https://cms.paypal.com/us/cgi-bin/?cmd=_render-content&content_ID=developer/e_howto_api_nvp_country_codes
Custom Subscribe Button URL
To use a custom graphic, globally, for all subscription buttons specify the graphic's valid URL in the Custom Subscribe Button URL setting. Custom graphic URLs specified in the button tag override this setting.
Custom Unsubscribe Button URL
To use a custom graphic, globally, for all unsubscribe buttons specify the graphic's valid URL in the Custom Subscribe Button URL setting. Custom graphic URLs specified in the button tag override this setting.
IPN Message Reattempt
Check the IPN Message Reattempt check box to allow PayPal to reattempt the sending of IPN messages which were not successfully received by the Nice Memberships extension.
Membership Listings Details
Current Memberships
The Current Memberships settings controls the display of members current memberships on the Nice Memberships default list page, i.e. yourdomain.com/index.php?option=com_nicememberships
Current List Title
This title is shown on the Nice Memberships default page, and on the core Joomla user profile page, above the list of the user's current subscriptions.
Current List Message
This message is shown on the Nice Memberships default page, and on the core Joomla user profile page, below the Current List Title.
Show Item Names
Check this box to display the membership name above it's respective subscription button on the Nice Memberships default page and on the core Joomla user profile page, in the Current Membership List.
Show Item Description
Check this box to show the membership item description above it's respective subscription button on the Nice Memberships default page and on the core Joomla user profile page, in the Current Membership List.
Show Membership Status
Check this box to display the user's subscription status of all current memberships.
Note, To disable the display of the Current Memberships listing on the Nice Memberships default page, uncheck Show Item Names, Show Item Description and Show Membership Status.
Available Memberships
The Available Memberships settings controls the display of members current memberships on the Nice Memberships default list page, i.e. yourdomain.com/index.php?option=com_nicememberships
Available List Title
This title is shown on the Nice Memberships default page, and on the core Joomla user profile page, above the list of memberships which are available, for subscription, to the user.
Available List Message
This message is shown on the Nice Memberships default page, and on the core Joomla user profile page, below the Available List Title.
Show Item Names
Check this box to display the membership name above it's respective subscription button on the Nice Memberships default page and on the core Joomla user profile page, in the Current Membership List.
Show Item Description
Check this box to show the membership item description above it's respective subscription button on the Nice Memberships default page and on the core Joomla user profile page, in the Available Membership List.
Note, To disable the display of the Available Memberships listing on the Nice Memberships default page, uncheck Show Item Names and Show Item Description.
Debug Settings
IPN Log
When the IPN Log setting is checked, the extension will record all incoming IPN messages, whether the message passes validation or not. The IPN Log will also list any reasons why the message did not pass validation.
*IMPORTANT: Please note that the IPN Log should not be left on for production sites. It is meant to be used during site testing only and is not suitable for other purposes. Leaving the IPN Log enabled on a live production site for long periods of time may cause some undesirable results.
The Nice Membership Plugins
Nice Membership Button Plugin
The Nice Membership Button plugin creates all subscribe and unsubscribe buttons on your site. It is required in order for the extension to function properly. This plugin must be enabled for button tag replacement to occur. To access this plugin go to Administrator>>Extensions>>Plugin Manager>>System - Nice Membership Button
This plugin has 2 parameters:
PayPal Test Mode
Setting this parameter to “on” will put all Nice Memberships buttons into test mode. Clicking a Nice Memberships button while it is in test mode will redirect the form submission to PayPal's sandbox.
Button Language Code
The Button Language Code sets your button language code. PayPal uses a 5 character code to designate language it's buttons. For example, United States English is designated with en_US. Enter the 5 character code for the desired button language. Other code examples are Great Britain English: en_GB, French: fr_FR, Spanish: es_ES, Polish: pl_PL, German: de_DE.
If you don't know the code for your desired language, log into PayPal use the button creator and search the resulting HTML code for this https://www.paypal.com/en_US/i/btn/btn_buynow_LG.gif. Notice the en_US in the URL, it's the language code for the button.
Nice Membership Expiry Plugin
The Nice Membership Expiry manages the expiration of memberships that have been canceled or have reached their end of term. This plugin is required in order for the extension to work properly. To access this plugin go to Administrator>>Extensions>>Plugin Manager>>System - Nice Membership Expiry
This plugin has 2 parameters. The 2 parameters control how often the plugin performs its expiration cycle. When the plugin runs its expiration cycle it checks the database for any membership subscriptions that are in need of expiring.
Amount of Time
How many units of time will pass before running the next expiration cycle, e.g. 12 hours, “12” is the number of units of time. Only enter numerical values in this field.
Time Units
The units of time to use when calculating the the amount of time between each expiration cycle, e.g. hours, days, weeks.
Nice Membership Redirect Plugin
The Nice Membership Redirect plugin redirects users to a pre-specified page, when the user logs in. This plugin is optional. It is not required for the extension to work properly. However, this extension is needed if you plan to request that users subscribe to a membership during the registration process. To access this plugin go to Administrator>>Extensions>>Plugin Manager>>System - Nice Membership Redirect.
There are 2 parameters for this plugin.
Redirect URL
The URL to redirect the user to, after login. By default this URL is set to index.php?option=com_nicememberships. The resulting page will list all available memberships to the user.
Redirect Criteria
This parameter dictates what criteria must be met in order for the user to be redirected.
Nice Membership Profile Plugin
The Nice Membership Profile is responsible for displaying membership information on Joomla's user profile page. This plugin is optional. Without it the extension will work correctly, but the user will not have access to their membership information on their profile page. To access this plugin go to Administrator>>Extensions>>Plugin Manager>>System - Nice Membership Profile.
There are no parameters for this plugin.