Smart Seller

Documentation

Installation

Go to Extensions -> Manage -> Install page, upload distribution package you've previously downloaded and click Install. Before you enable extension you must setup it first.

For plugins: Go to Extensions -> Plugins, find the desired plugin and open its settings. Setup accordingly and only then enable.

For modules: Go to Extensions -> Modules, find the desired module and open its settings. Setup accordingly and only then enable.

For components: Hover your mouse over Components menu item, find the desired component and go to Options page. Setup everything accordingly and don't forget to check Permissions tab.

License ID: Enter anything in License ID field, if it is present in extension options.

PayPal Settings

First of all, you have to register PayPal account, if you don't have any. When you done, install Smart Seller from Extension Manager as usual and setup according to your liking. If you don't understand, which option means, read a short description of it in a hint or look for more information in Settings section below.

Multiple currencies

If you want to accept payments in different currencies, you need to change payment receiving preferences in your PayPal profile. Go to Profile -> My Selling Tools, locate Block Payments option and click Update. On the Payment Receiving Preferences find "Allow payments sent to me in a currency I do not hold" option and select "Yes, accept and convert them". If you don't do so, all payments in any currency besides USD and your local one will have Pending status. You will have to login to PayPal and manually accept such payments. Only after that transaction will be completed and order added.

Names encoding

For better compatibility with non-Latin names set PayPal encoding to UTF-8:

• Go to your PayPal profile.
• Click "My selling tools" in the sidebar.
• Scroll to the bottom of the page and click "PayPal button language encoding".
• Click "More options" and set the encoding to UTF-8.

If you don't set encoding to UTF-8, some customer names in Russian, Chinese or other non-Latin languages will be messed up.

Options Description

You will always find a short description of any option in its hint on Smart Seller settings page. Below is more detailed description of each option.

General Settings

• Add jQuery — Adds jQuery library to your site on page load. Disable, if another jQuery instance is already loaded.
• Storage folder — Path to the folder, where you keep all your files. Must be a path, NOT URL! Something like /home/public_html/files.
• File prefix — A prefix, which will be added to file with each download.
• Allowed extensions — List of allowed file extensions, which will narrow file scan and keep all other files intact.
• Free download groups — List of groups, which will always have access to all files from your site.
• Approve orders — All orders will be unpublished by default and you have to publish (approve) them manually.
• Auto register — For all not registered buyers a new account will be automatically created.
• Auto add — If set to Yes, order will be added to existing user account, when user is not logged in. His PayPal email must match Joomla account email.
• Auto renew — If set to Yes, expired orders from the same customer will be renewed; No — new order will be created. If customer bought one file multiple times, last purchase will be renewed.
• Delete physically — If set to Yes, files will be deleted from your hard drive, when you click Delete or Empty button in admin.
• Smart hide — Enables hiding content from everyone except license owners.
• Use captcha — Enables captcha in review form and any other submissions.
• Success page — Create an article or any other type of content and set a menu item for it. Customer will be redirected to this page upon successful payment.
• Cancel page — Create an article or any other type of content and set a menu item for it. Customer will be redirected to this page, if he cancels payment.
• From name — Sender's name for all notifications and reminders. If not set, name will be taken from global mail configuration.
• From email — Sender's email for all notifications and reminders. If not set, email will be taken from global mail configuration.
• Attach files — If set to Yes, purchased file will be attached to notification email.

Layout Settings

• Button type —  How your payment button will look like: image or text.
• Bundle button —  Use full layout for bundle button (like for file button) or compact one.
• Date format — Desired date display according to PHP date() function format.
• Show title — If set to Yes, file title will be displayed with PayPal button.
• Show price — If set to Yes, file price will be displayed with PayPal button.
• Show free — Price will be displayed, even if it equals zero. "Free" word will be used instead.
• Show bundled — Bundle contents will be displayed across the site (e.g.: on My Orders page).
• Show version — File version will be displayed across the site (e.g.: on My Orders page).
• Show size — File size will be displayed across the site (e.g.: on My Orders page).
• Show footer — If set to Yes, a small block with additional info about security and accepted payment methods will be displayed.
• Show converter — Displays price converter with PayPal button.
• Show dates — Displays discount start and end dates with PayPal button.
• Back-end Options section — Allows you to select different columns for files, orders and other lists.

Converter Settings

• Enable converter — Turns on/off currency converter.
• Currencies list — List currencies, which will be available to convert into.
• Add fee — A fee in percent to compensate some losses during conversion.
• Update period — How often currency rates will be updated.
• Round type — Conversion usually returns price with decimals. You may round them to set number of decimals or raise/lower it to the highest/lowest integer.
• Round by (Standard only) — Price decimal value will be limited by given number (e.g.: 16.4536 will become 16.45 if round value is 2).
• Price precision — How many digits will be displayed after integer in converted price.

PayPal Settings

• Sandbox mode — PayPal test mode. No actual money will be withdrawn during transaction. Don't forget to set it to No, when you finished with testing.
• Business name — You company or any other name, which will appear on PayPal payment form. Do NOT set it, if you account is not Business type!.
• PayPal email — You PayPal login (required!).
• Tax value — Tax or VAT value in percent (optional).
• Base currency —  Your base currency, which will be used by default (optional).
• PayPal country — Your PayPal country (optional).
• Process pending — If set to Yes, for transactions with Pending status a new unpublished order will be created and will be published automatically, when you manually accept the payment in your PayPal account. Otherwise new order will be created only after payment accepted.
• Send export — A truly geek feature, which will send you a bunch of info about payment.

Notifications

• Enable notifications — If set to Yes, customer will receive a notification with information about his order. For example, you may create a Thank You article with download link and order info.
• Order added — Joomla article, which will be used as a notification about new order.
• Order approval — Joomla article, which will be used as a notification, when new order requires approval.
• Order renewed — Joomla article, which will be used as a notification about renewed order.
• Order updated — Joomla article, which will be used as a notification about updated order.
• Order (un)published — Joomla article, which will be used as a notification, when order was published or unpublished.
• Order deleted — Joomla article, which will be used as a notification, when order was deleted.
• Review added — Joomla article, which will be used as a notification about new review.
• Review updated — Joomla article, which will be used as a notification about updated review.
• Review (un)approved — Joomla article, which will be used as a notification, when review is approved or declined.

Reminders

• Enable — Enables sending of particular reminders to customers (one per each reminder).
• Emails per cycle — How many reminders will be sent per one pass. Do not set it too high, or you might get banned by your hosting provider!
• Send report — A report about processed reminders will be sent to your email after each cron job.
• License expires — Reminds customer about expiring license, if it has less days left, than Send Before option, and more, than zero.
• License expired — Notifies customer about expired license in set number of days defined in Send After option.
• Follow order — Sends a follow up email after set number of days defined in Send After option and if license is active.
• Article — Joomla article to be used as a certain reminder.
• Send before/after — Number of days before or after certain event (see description of the reminder).
• Recurring — If set to yes, reminder will be send in set number of days over and over again. Otherwise reminder will be sent once.

Global discount

• Enable discount — Turns on/off a global discount for all files.
• Type — Type of global discount. Discount — works for all files 24/7. Coupon — works only when coupon code entered before purchase.
• Discount title — Optional discount title. For example, "Black Friday 40% OFF".
• Coupon code — Set of digits and letters, which customer should enter in Coupon field before purchase to get a discount.
• Value — Discount value. Can be set as fixed amount or percentage.
• Coupon uses — Number of times coupon can be used per customer. 0 — unlimited and available for everyone, including guests, 1 and more — customer must login to enter coupon name.
• Start date — When global discount starts.
• End date — When global discount ends.
• Groups — Joomla groups, which are eligible for discount (leave empty for all).
• Affects renew — Discount will be also applied to renewed orders.

Reviews

• Enable reviews — Turns on/off review and rating system.
• Review ordering — Reviews will be sorted from old to new (ascending) or from new to old (descending)
• Reviews per page — How may reviews will be displayed on one page.
• Customers only — Only customers (with or without active license) will be able to write reviews to the files they own or owned.
• Submit interval — Simple flood control option in seconds to avoid submitting a large amount of reviews.
• Form position — Where review form will be displayed: above or below reviews list.
• Collapse form — If set to Yes, form will be collapsed by default.
• Show rating — Adds rating stars to review form and reviews list.
• Rating score — How many starts rating will have.
• Show author — Adds author name to review form and reviews list.
• Show email — Email field is enabled and required in review form.
• Show title — Adds review title to review form and reviews list.
• Show date — Shows submission dates in reviews list.
• Notify admin — Administrator will be notified about new reviews.

Export

• Enable export — Turns on/off export feature. Saves various information from database to XML file.
• XML file — XML file name, where export information will be stored. File will be saved in the root folder of your site.
• Files Export section — Enables XML export for different file information fields.

Permissions

A very important section, where you can set restrictions for different actions on front-end and back-end. Every permission has a hint, which explains its meaning. Don't forget to setup this section before going live!

Smarseller Markers

There're several markers available, one for each task. You can have any number of markers of any type on one page — they'll be properly processed and replaced with actual content.

PayPal button

This is the easiest part. Just insert a button marker anywhere you want and it will be replaced with PayPal button, price, currency converter, etc.:

{smartseller=ID}

ID — desired file ID, which you can find on Files page in your back-end. That's it.

If you want to display custom text instead of generic PayPal button, wrap this text in tags like this:

{smartseller=ID}Some text{/smartseller}

In this case marker will be replaced with "PRICE Some text", where PRICE — desired file's price or "FREE Some text", if price is zero.

Reviews section

Similar to PayPal button just insert a reviews marker anywhere you want and it will be replaced with submit form and list of existing reviews:

{smartreviews=ID}

ID — desired file ID or IDs separated by comma, which you can find on Files page in your back-end.

Hide content

You can hide any content from users, who don't have active license to particular file. This can be useful, for example, when you don't want to show documentation, usage instructions or any similar kind of essential information. To hide content, just wrap it in smarthide tags like this:

{smarthide=ID}Some text{/smarthide}

ID — desired file ID, which you can find on Files page in your back-end.

Creating Bundles

Bundle is a sets of files, a package, which you can sold separately for its own price. To create a bundle, add a new file, choose Bundle as Type and name it. After that select this bundle from dropdown menu for all the files you want to be bundled. When customer downloads bundle, all bundled files will be packed in separate archive on-the-fly. You don't have to add bundle physically.

Using Tags

In notifications and reminders you may use tags like {tag} or {tag}Some text{/tag}, which will be replaced with actual values before sending an email to customer. Simple tag {tag} will be always replaced with actual value, even if the value is empty or zero. For example, {expires} will be replaced with set number of license period in days. Double tag {tag}Some text{/tag} is good, when the value is optional and you don't want it to be displayed, when not available. It means, that {expires}License period:{/expires} will be replaced with "License period: 180 days" if file has this value set and will be hidden if this value is zero.

Order

• orderid — current order ID;
• date — order payment date;
• daysleft — how many days left until license expires (including "days" word);
• downsleft — how many downloads left until license expires (including "downloads" word);
• downlink — file download link.
• firstname — customer's first name;
• lastname — customer's last name;
• email — customer's email address;

File

• fileid — ID of the purchased file;
• filename — file name (for example, somefile.zip);
• filetitle — file title (for example Some File);
• version — file version;
• description — file description;
• price — file price;
• currency — file currency;
• domains — list of domains, connected to purchased license;
• expires — file licensing period in days (including "days" word);
• downlimit — file download limit (including "downloads" word);
• reqlogin — use it, if user must login to download file;
• reqregister — use it, if user must register to purchase file;
• filepage — will be replaced with link to the page with purchased file (if set) and file title;

Reviews

• reviewid — review ID;
• reviewtitle — review title;
• reviewtext — review text;
• rating — review rating;
• author — review author's name;

Common

• date — item date;
• userid — Joomla user ID;
• status — Item (order, review, etc.) status: published (approved) or unpublished (declined).
• ip — user's IP-address (multiple addresses, when available);

Send reminders

If you want to send reminders, use the following command for cron job (or launch URL from it manually):

lynx -source 'http://yoursite.com/index.php?option=com_smartseller&task=remind&secret=XXXXXX'

ХХХХХХ — secret key, which is stored in database. You'll find your personal string with secret key on the main page of the component. If you don't want to receive any reports, put this command at the end of the above string:

> /dev/null

Events and Plugins

Smart Seller has integrated events system, which allows you to create plugins to expand main extension's functionality. Here's a list of all currently available events:

onSmartSellerPrepareFile(&$file, $order)

Triggers, when file is prepared for download. You may do anything with it: add other files to package, rename file etc.

$file — An object with all file attributes, which must be returned.
$order — An object with order attributes (date, customer's name, email, country etc.).

onSmartSellerFormCreate(&$form, $file)

Triggers, when peyment form is created. You may add any other stuff to the beginning or the end of the form, any extra information: text, HTML, iimages etc.

$form — Fully prepared HTML form, which must be returned.
$file — An object with all file attributes.

onSmartSellerCheckOrder(&$result, $order, $file)

Triggers, when file is checked on availability before downloading or displaying payment button. You may add any other checks here (for example, subscriptions).

$result — Boolean type value, which must be returned.
$order — An object with order attributes (date, customer's name, email, country etc.).
$file — An object with all file attributes.

onSmartSellerGetSubscriptions(&$file)

Triggers, when opening file page on back-end, checks for extra subscription to create extra form fields.

$file — An object with all file attributes. $file->subscriptions array should be filled with values. Here's a list of available keys:

• source — Subscriptions source.
• title — Subscriptions source title.
• items — An array of items like subscription levels or subscriptions themselves with two keys: 'id' and 'title'.

You can have unlimited number of subscriptions for each file activated subscription plugins and they all will be checked before downloading or displaying payment button.