PaidListings Add-on Manual for Joomla

Last update: April 29th, 2015

Copyright © 2010-2015 ClickFWD LLC

Chapter 1 Overview & Installation

1.1 PaidListings Add-on Overview

The PaidListings Add-on allows you to monetize your website by accepting payments for submission of commercial listings as well as listing upgrades. Use it for classifieds, real estate listings, city guides and more.

You can create base and upgrade plans, with one time or subscription payments and associate them with specific categories. Each plan can include a set of custom fields, a specific number of media and make the listing featured.

Pricing plan can include:

a set of custom fields

specific number of media (photos, videos, attachments, audio)

option to make the listing featured

additional options by using custom variables

Available payment types:

One Time Payment

Subscription

Free or Trial

Payment Handlers

PaidListings Add-on comes with payment handlers for Paypal, 2Checkout and Authorize.net. Only Paypal supports subscriptions at this time.

Offline payment option is also possible, as well as the ability to pay with AlphaUserPoints or JomSocial points.

Email Notifications

The add-on can email both user and administrator at different times like order placement, payment processing and plan expiration. The email templates are customizable via the admin interface.

Coupons

The add-on has coupon configuration options unlike anything you've seen before. Coupons can be configured for specific dates, plans, users, categories and number of times used.

Tracking code

Adding Javascript tracking code for systems like Google Analytics is as simple as pasting the correct code in the pre-defined tracking fields in the configuration. There's no need to edit theme files. The add-on even provides special {tags} you can use in the code like order id, order amount and plan name.

Seamless integration

The add-on integrates seamlessly with JReviews without the need for theme changes. The JReviews admin already has theme changes necessary to show pay-related info of listings in the moderation and browse screens.

1.1.1 Examples of PaidListings usage

PaidListings Add-on is great for many types of websites, for example Classifieds, City Guides, Product reviews sites, ...

Your pricing plans can be organized like this:

one basic plan for listing submission - free or small price, with a set of custom fields and specific number of media

one or more premium plans for listing submissions - higher price, with larger set of custom fields, higher number of media, and other features like inquiry form, ...

one or more listing upgrade plans – listing upgrade plans are used to upgrade previously purchased basic or premium plan with additional custom fields, additional media or to make the listing featured

Example of Pricing Plan Overview page on a Classifieds website:

1.2 Installation

The add-on can be installed via the Remote Install & Update menu in the JReviews administration.

To install or update the addon you must have previously purchased it, your JReviews version needs to match or be greater than the one specified for the addon and you must have a valid "Upgrades & Support" package for your JReviews license.

If you purchased the addon, but it still says "addon not active for this license", go to the JReviews admin license screen, clear the local key text area and re-submit the license number. This will fetch a new local key that includes the addon information.

On the Install & Update page, check the Updates checkbox, and click on the Install button next to the PaidListings Add-on like on this image:

Reload the page to see the PaidListings link appear under the Add-ons header on the left sidebar:

Chapter 2 Configuration

2.1 General Settings

Enable stealth mode - the stealth mode should be enabled only if you installed the PaidListings add-on on an active site where users are allowed to submit listings for free. To avoid problems with those existing listings, enable the stealth module until you setup the pricing plans and generate orders for all existing listings. Regular users will not see the effects of the PaidListings add-on when the stealth mode is enabled. After you finish the PaidListings setup, disable the stealth mode for users to be be able to see the plans and purchase listings.

Enable TOS in final order step:

No

Yes, without checkbox - the user agrees with TOS by completing the order

Yes, with checkbox - the user needs to check the checkbox to agree with TOS before completing the order

TOS Article ID - enter the ID of the TOS article from the Joomla Article Manager.

Company Logo Image - here you can set the path to your company's logo that will be included on invoices.

Your Business Information - your address, phone and other info for the invoice.

Users will be able to enter their information for the invoice on the My Account page. On the same page they will find a button for a printable Invoice next to each order.

Here is an example of an invoce:

If you want to change the look of the invoice, edit this theme file: /components/com_jreviews_addons/paidlistings/views/themes/paidlistings/paid_invoice/index.thtml

2.2 Cron

Here you can set cron periods for scheduled PaidListings actions.

PaidListings cron actions will use the settings you have chosen in the JReviews Configuration, Cron tab. Try to set the cron periods at different intervals so all scheduled actions don't run at the same time.

2.3 Expiration Notifications

Choose when will users get notification emails for plan expiration.

2.4 Tracking

Important!: Google Analytics tracking code must be already loading on your site. It is recommended to leave this step for last after you configure PaidListings because using incorrect tracking code will cause issues with the add-on functionality.

You can insert Javascript tracking code for Google Analytics, for the following order flow steps:

Paid Category Selection in Submit Listing Form - user selects a paid category when submitting a listing

<script type="text/javascript">
  try {
      ga('send', 'pageview', '/paid-category-selected');
  }
  catch(err) {
      console.log("Error tracking Paid Category Selection:", err.message);
  }
</script>

Submit Listing - plan selected and listing submitted.

<script type="text/javascript">
  try {
      ga('send', 'pageview', '/listing_submission');
  }
  catch(err) {
      console.log("Error tracking Listing Submission:", err.message);
  }
</script>

Order Form - order form dialog shown.

<script type="text/javascript">
  try {
      ga('send', 'pageview', '/order_form');
  }
  catch(err) {
      console.log("Error tracking Order Form:", err.message);
  }
</script>

Submit Order - order submitted. Valid tags: {order_amount}, {order_id}, {plan_name}

<script type="text/javascript">
  try {
    ga('require', 'ecommerce');
    ga('send', 'pageview', '/order_submission');
    ga('ecommerce:addTransaction', {
      'id': {order_id},
      'revenue': {order_amount},
    });
    ga('ecommerce:addItem', {
      'id': {order_id},
      'name': "{plan_name}"
    });
    ga('ecommerce:send');
  }
  catch(err) {
      console.log("Error tracking Order Submission:", err.message);
  }
</script>

Order Complete - order complete page. Valid tags: {order_amount}, {order_id}, {plan_name}

<script type="text/javascript">
  try {
    ga('require', 'ecommerce');
    ga('send', 'pageview', '/order_completed');
    ga('ecommerce:addTransaction', {
      'id': {order_id},
      'revenue': {order_amount},
    });
    ga('ecommerce:addItem', {
      'id': {order_id},
      'name': "{plan_name}"
    });
    ga('ecommerce:send');
  }
  catch(err) {
      console.log("Error tracking Order Complete:", err.message);
  }
</script>

2.5 Taxes

If your country's business regulations require to charge taxes, here you can setup the tax percentages.

Chapter 3 Payment Handlers

PaidListings Add-on comes with these payment handlers:

For other payment handlers, a plugin can be written.

It is not possible to test the add-on on localhost when you use it to make payments with Paypal, 2checkout and other payment processors. These send a reply back to your site to update the order information so the site needs to have a valid reachable domain.

3.1 PayPal

PayPal payment handler has 3 states: Disabled, Enabled and Sandbox.

Sandbox is used for testing. To use it, you must first get a PayPal developer account here: https://developer.paypal.com

3.2 2Checkout

3 states: Disabled, Enabled and Sandbox.

Secret word can be found under Account => Site Management in the 2CO site.

3.3 Authorize.net

3 states: Disabled, Enabled and Sandbox.

Testing can be done with the production or test gateways. For the test gateway you need an Authorize.net developer account, but if Sandbox is selected above you can still perform test transaction on the production gateway.

Secret word is configurable value in the Authorize.net Account Settings, required for authentication. Leave empty for development accounts.

3.4 Offline Payments

2 states: Disabled and Enabled.

After users submit a listing and order a certain plan, they will be redirected to a page with Payment instructions.

3.5 JomSocial Points

If you use JomSocial extension and enable the JomSocial Points as payment handler, users will be able to "pay" for listing plans using the points they earned on your site.

3.6 AlphaUserPoints

If you use AlphaUserPoints extension and enable the AlphaUserPoints as payment handler, users will be able to "pay" for listing plans using the points they earned on your site.

3.7 Changing payment buttons

When users order a plan, they will see the buttons of all payment handlers that you enabled. This is how payment handler buttons look like by default:

For every payment handler you can change the button image by entering the Path to image in the handler's settings:

Chapter 4 Pricing Plans

4.1 Pricing Plans Overview

There are two types of listing plans:

Base - a base plan that is available with new submissions or when an existing base plan expires.

Upgrade - an upgrade plan which extends the features of a base plan (before the base plan expires).

4.1.1 Base Plans

When users go to the "Submit New Listing" page and select a category, they will see a list of all plans available for the selected category, for example:

When creating a certain plan, if you make it default, the plan will be pre-selected on the listing submit form.

Users can click on different plans and the listing submit form will automatically display/hide fields based on their availability in certain plans.

When a user submits the listing, the next step will be choosing the payment method and making an order.

Before confirming the order, user will be able to enter a Coupon if it exists.

The listing will be published after the user completes the payment.

4.1.2 Upgrade Plans

If you create Upgrade Plans, listing owners will see an "Order Upgrade" link next to their listings. When they click on the link, they will see a list of all upgrade plans available for listings in category where their listing is submitted, for example:

The process of ordering an upgrade plan is the same as ordering a new listing plan: Step 2 is selecting payment method and step 3 is entering a coupon and confirming the order:

4.2 Creating Pricing Plans

To create a Listing Pricing Plan, click on the Pricing Plans link under the Paidlistings Setup menu.

Click the New button in the top right corner and you will get the New Pricing Plan form:

Enable - must be set to Yes if you want the plan to be available for purchasing.

Show in submit form - allows you to hide the plan from the list that appears after category selection. This can be useful in implementations where new listings are free (an example is available in the FAQ section of this manual).

Default Plan - appears pre-selected in the order page. There can be only one default plan of the same type (base or upgrade) per category.

Plan type:

Base - a base plan that will be available only for new listings and when existing base plan expires.

Upgrade - an upgrade plan that will be available only for listings that have a certain base plan applied to add more features to the base plan before it expires.

Payment Type:

One Time Payment - the user makes a single payment when ordering a plan for the first time. After the plan expires, the user will need to go through the process of paying for the next period again to keep the listing published.

Subscription - subscriptions are handled by payment processors. Currently, only PayPal supports subscriptions (recurring payments). When the user orders a subscription plan, PayPal will setup recurring payments and after the plan expires, the user will be automatically charged for the next period. The subscription will run until the user cancels it in Paypal.

Free or Trial - the user doesn't have to pay anything. When adding a free or trial plan with an expiration remember to setup a paid plan for the same categories so users can keep their listings published.

Free/Trial Limit - if you select Free or Trial as payment type, you can limit the number of times this plan can be used with different listings. Leave empty for no limit.

Duration - Days, Weeks, Months, Years, Never Expires.

If the Plan you are creating is Upgrade plan, the duration must be set like this:

if the base listing plan never expires - you can set any duration for the upgrade plan.

if the base listing plan has an expiring date - you must set "Never expires" for the upgrade plan and it will expire together with the base plan.

Action after expiration - choose if the listing will be unpublished after the plan expires or a new Free/Trial plan order will be created.

Description - use this field to to provide more details regarding the plan, it will be displayed below the plan name on listing submit page and the plan overview page.

Moderation - if set to Yes, new listing will be left unpublished until approved by admin, even if the user paid for listing submission.

Featured - if set to Yes, the submitted listing will become Featured.

Category & Custom Field Assignment - first choose for which categories the plan will be available and then you will be able to choose which custom fields will be included.

Enter the total number of media items that users will be able to upload for each media type. Leave empty to use the global media count setting for each media type or to default to the base plan setting if this is an upgrade plan.

Custom variables provide additional flexibility to your pricing plans. The variables are made available in the theme files so you can use them for customizations. For example, you can show/hide specific page elements based on the variables that are included in the plan.

Custom variables are explained in detail in the Tips & Tricks chapter.

Chapter 5 Coupons

5.1 Creating a coupon

To create a coupon click on the Coupons link under PaidListings Setup menu and click on a New button. You will get a Create Coupon form:

Name – this is the actual coupon code that users will be able to use when ordering a plan.

Valid for renewals only - if set to yes, the coupon will not be available for new listing payments.

Dates - you can set the date period when the coupon will be valid. If you leave the dates empty, the coupon will be always valid.

Count - you can limit the number of times a coupon can be used, per user or for everyone, leave empty to ignore.

Restrict to Users - coupon will be valid for everyone unless you select certain members of your site.

Restrict to Plans - coupon will be valid only for selected plans.

Restrict to Categories - you can restrict the coupon to specific categories.

5.2 Using coupons

Coupons codes are not displayed anywhere automatically. Only users that find out about the coupons will be able to use them. For example, you can include the coupon codes in promotions, newsletters or notify the users directly via your site or email.

Example of the coupon usage:

After users order a plan and select the Payment Method, on the last step they will be able to enter a coupon code:

After clicking the Apply button, a discount will be applied:

Chapter 6 Email Notifications

On the Email Notifications page in PaidListings Add-on administration you can enable notification emails for various listing order actions:

First two are admin notifications that are sent to the email addresses of admin(s) that you specify.

User notifications will be sent to the user's email address. Optionally, you can enter your email address to the Admin BCC emails if you want to receive copies of emails that are being sent to users.

To adjust the email template, click the Edit button in the last column:

Enter any text that you want for the Subject and Body of the email. Tags like {user_name} will be automatically replaced with the actual values:

Chapter 7 Menu Items

PaidListings Add-on has two types of menu items:

Category Plans - overview of available pricing plans

My Account - page where users can manage their listings, orders, invoices, account details, etc.

7.1 Category Plans Page

The Category Plans page displays all plans available for certain category. Visitors can click on "Submit" button and they will be redirected to the Listing Submit page with the plan pre-selected. If you have a default plan for the category it will appear highlighted (orange background).

To show the plans page to your visitors, you will need to create a new JReviews menu item:

Go to one of your menus in Joomla Menu Manager where you want to include the plans page and click the New button:

Next click the Select button:

Choose PaidListings Plans as menu item type under JReviews:

Enter the name of the menu item and optionally you can select a specific category if you want to have separate plans pages for different categories:

If you don't select a category, the plans page will show all pricing plans that you created for all categories.

Here is an example of the Category Plans page:

7.2 My Account Page

On the My Account page users can manage their listings, orders, invoices, account details, etc.

To create the My Account menu item, follow these steps:

Go to one of your menus in Joomla Menu Manager (User Menu is recommended) and click the New button:

Next click the Select button:

Choose PaidListings MyAccount as menu item type under JReviews:

Select Registered in the Access parameter because only logged in users are supposed to access the My Account page:

Here is an example of the My Account page:

Chapter 8 Tips & Tricks

8.1 How to use custom variables

Custom variables provide additional flexibility to your pricing plans. The variables are made available in the theme files so you can use them for customizations. For example, you can show/hide specific page elements based on the variables that are included in the plan.

To set custom variables, edit your pricing plans and in the Advanced tab add the variable name and variable value in this format:

To access the custom variables use this code:

<?php echo $Paid->getVar('var1',$listing);?>

8.1.1 Simple example of creating conditionals in the theme files based on custom variables

Let's say you created 3 plans: Free, Basic and Premium.

For each of those plans you can set a variable with the same name, but different value, for example:

In the Free plan enter this:

plan_type|free

In the Basic plan enter this:

plan_type|basic

In the Premium plan enter this:

plan_type|premium

Then in the theme files (i.e. /listings/detail.thtml) you can create conditionals like this:

<?php if ($Paid->getVar('plan_type',$listing) == 'free'): ?>

    This is a free listing.

<?php elseif ($Paid->getVar('plan_type',$listing) == 'basic'): ?>

    This is a basic listing.

<?php elseif ($Paid->getVar('plan_type',$listing) == 'premium'): ?>

    This is a premium listing.

<?php endif;?>

Listings that have the Free plan would output "This is a free listing.", listings that have the Basic Plan would output "This is a basic listing.", etc.

This way you can show/hide different parts of theme files based on the custom variable value.

8.1.2 Adding Inquiry Form to listings based on the custom variable

Let's say you want to show the inquiry form on listing detail pages, but only for listings whose owners purchased the Premium plan.

In the Premium plan you can add a custom variable like this:

inquiry|enabled

In the theme file of the listing detail page (/listings/detail.thtml) you can add this code:

<?php if ($Paid->getVar('inquiry',$listing) == 'enabled'): ?>
    <?php echo $this->element('inquiry_widget');?>
<?php endif;?>

This code would display the inquiry form only in listings whose owners purchased the plan that contains the inquiry custom variable.

To use this approach for the Inquiry Form, you first need to disable the default inquiry functionality in JReviews Configuration, Listings tab. You need to set Enable Listing Inquiries to No.

8.2 How to allow free listing submissions and charge only for listing upgrades

If you want your users to submit listings for free but charge them for additional features like making the listing Featured, adding additional custom fields, ..., it is still required that you create a base plan because upgrade plans are not available if a base plan is not applied to a listing.

In this case you must create only one base plan and select Free or Trial as Payment type.

Make the plan default, and if you set Show in submit form to No, users will not see the plan when submitting a listing, but this free plan will be processed automatically.

This will make it possible for listing owners to Order Upgrade and pay only for special features that you created as listing upgrades.

Existing Listings (using bulk order generator)

If you create a listing plan for a category that already has listings (created before listing plans were available), all media and custom fields will be hidden in those existing listings.

For existing listings you need to create a free base plan that will include the images and custom fields.

When you save the free listing plan, you will see a Create orders button next to the plan. When you click this button, it will generate orders and apply this free plan to all existing listings that don't have a plan:

8.3 How to allow administrators to submit listings without payment

When you create pricing plans for certain categories, it will not be possible to submit listings without ordering and paying for submission to those categories.

To allow certain users (administrators) to submit a listing without payment, you can create a Coupon with 100% discount.

Here is an example of the coupon settings:

The name of the coupon is the actual coupon code that the admins will need to use when ordering a plan.

Discount is set to 100 and in Restrict to Users only the administrator (Super User) is selected.

When submitting a listing, administrator will need to select a plan, and later enter the coupon code when confirming the order.

8.4 How to filter Listings and Geomaps modules to entries with specific plans

It is possible to filter the output of the modules and even the JReviews Custom List menu by adding a CUSTOM WHERE statement that looks like this:

(Listing.id IN (SELECT DISTINCT listing_id FROM #__jreviews_paid_orders WHERE order_active = 1 and plan_id = 5))

If you want to match multiple plans the statement can be written like this:

(Listing.id IN (SELECT DISTINCT listing_id FROM #__jreviews_paid_orders WHERE order_active = 1 and plan_id IN (4,5,6)))

Make sure you change the plan_id(s) to match the ids of your paid plans.

Chapter 9 Troubleshooting

9.1 Why existing listings lost images and fields after creating a plan for existing categories

If you create a listing plan for a category that already has listings (created before listing plans were available), all media items and custom fields will be hidden in those existing listings. That is because every listing must have an active order for its data to show up.

The solution is to create a free base plan that will include all media items and custom field. Then you will be able to generate free orders for all existing listings.

After you create the free plan, click this button to generate orders for listings:

In the popup you will see the number of remaining listings without orders and you need to click the Start button to generate orders for those listings: