UserPoints Support in jDownloads

Introduction

The organisation Remositry has a Joomla 4/5 version of a 'points system', called UserPoints, like the now defunct Alpha User Points and Alta User Points used in Joomla 3. Critically UserPoints uses the same database structure as the Alpha/Alta versions. 
jDownloads 4.0.42 (released 12 April 2024) and UserPoints 4.1.11 (released 5 April 2024) are compatible with each other.
User Points has the same database structure as the Joomla 3 versions so upgrading from either of the Joomla 3 User Points versions, that is from either 'Alta User Points' or 'Alpha User Points', is simple.  See the Appendix below for details about Joomla 3 versions.

User Points is supported in jDownloads though the use of five jD specific 'rules'.  The User Points component must of course be installed.  The official User Points documentation often refers to these 'rules' as plugins which is very confusing as they are not plugins in the normal Joomla! sense.  However there is no cause for concern as the User Points has a function in its control panel to connect up these rules.

The objective here is to provide a guide on setting up User Points as far as interaction with jDownloads is concerned.  These notes are not a guide to using User Points in other situations.  However it is useful to briefly describe the use of User Points in a jDownloads context.  Basically each time a user downloads then their User Points 'account' is reduced by a certain number of points.  This may be a fixed number of points per download or it may be the amount specified in the jD 'Price' field associated with that Download. Users may gain points by creating a new Download.  Also points may be given to the Download 'owner' each time a user downloads one of their Downloads.

Become a Remository Observer


To Download User Points, you will need to create an Account on Remositry as a Remository Observer.  This is free.

As an Observer, User Points is free for downloading.

Go to Remository Membership (opens in a new tab/window).

Then Click on button sign upThis takes you to a New User form.  So fill in the relevant details when done click on the button proccess subscription.
Remository Observer

Installation


The first step is to install the User Points component. 

Installation, and updating, is quite straight forward and is similar to installing  jDownloads.

To get User Points go to
 https://remository.com/downloads/A-Place-for-User-Points/ (opens in a new window/tab).

Scroll down to the 'Files in A Place for User Points' and click on 'User Points 4.0.6' or later.

The latest release of User Points from Remositry at the time of writing is version 4.1.11 .

files in a place
After installing User Points and before using it there are a few things to set up in both jDownloads and User Points configurations.

Setup jDownloads for User Points

In jDownloads go to the V4 button control panel and select button options, which is top right, then go to the tab specials tab. 
Then scroll down to  section "Settings for 'User Points' support (formerly: AlphaUserPoints/AltaUserPoints)" which needs completing.  When you set  "Use 'User Points' Rules " to Yes, it reveals two further settings as shown below.

  1. Use 'User Points' rules?  Set to Yes if you want to use in conjunction with jD. When set to Yes it reveals the next two settings.
  2. Use files price field for points?  This is where we select using either a fixed number of points per download or a variable number of points per download as specified in the jD Price field associated individually with every Download. 
  3. The final item is setting the 'hint' if the user does not have enough points.  This supports multilingual sites.
User Points 41
For initial testing it is simplest to use No for the 'Use Downloads Price Field for Points' option.  This means that every Download will be affected, which may be inconvenient.  For serious use of the system using Yes is probably better as you can then have a mixture of 'free' and different charge rates for downloads.
Please note we have not tested the UserPoints 'Purchase Points for money' as that is not related to jDownloads.

Price Field For Points

There are three stages to setting up price/download. The first step is to set the 'Use Downloads Price Field for Points' to Yes in the button specialstab.
V4 UserPoints Yes
The second step is to go to the jDownloads jD Control Panel, and select V4 button user groups setting
Next we select which User Group or Groups will, in principle, be charged for a Download.
In V4 button usergroup select  the V4 tab groupcreate edit tab and scroll down to the 'tick box' section. In the Additional Tab section ensure that option Price is set,
V4 additionalTab Price
The third and final stage is to set the price field in each Download. This is the first item in the Additional Data tab of each Download.

The Downloads list shows the Price. You are also able to sort by price as shown on the far right.
V4 SetPriceV4 DownloadsListPrice

Viewing User Points

The User Points points dialogue is shown by the Summary Layout through the place holder {aup_points_info}. This is already present in the Standard Summary layout.


The next jD item to set is to ensure that the Summary page will be shown so that the user knows the number of points they are "paying".
That is set in V4 button optionsV4 tab frontend tab  and scroll down to the Download Sequence.

Set  'Activate Direct Downloading' to No as shown opposite.  The other three fields may be set as required.  For more information please see the article Download actions: Direct, via Summary Page or via Download Details (opens in new widow/tab).
User Points 43
As noted above, the Summary page will inform the user of the cost of the Download in points.  In this example, as shown opposite, the cost is 1.75 points and the user's 'credit' is 5.00 points.  The Download button is shown.

Note: jDownloads shows a maximum of 2 decimal places.
User Points 65

However if the user does not have sufficient points then an advisory 'error' message shows the shortfall.

Also, of course, no Download button is present.
User Points 67C

Another situation is where users are not logged in but the Download appears downloadable as a Download button is being shown. 

In this case because User Points is active and set up so that only logged on users may download then jD detects this and generates a message such as the one opposite.
User Points 77
There is one more aspect of jDownloads that may need to be considered. This is the 'Download Duration Restriction' in the Limits tab of  User Groups Settings.  This setting allows a grace perod in which a user may make multiple downloads of the same item without incurring additional 'charges'.  The objective of this parameter is to cover situations where a download may fail.

See the note below about Download Managers.  In practice it means that if you are testing do not download the same Download each time as it will seem that the system is faulty!  Also do not confuse with the 'Activate Waiting Time' value in the 'Group Settings' tab of User Groups Settings.  The 'Activate Waiting Time' merely introduces a count down time before downloading starts.

Setting Up User Points


After installing User Points go to the  Control Panel.  This has a large number of icons as illustrated opposite.

Only part of the User Points Control Panel is shown opposite.

It may also have a message about Synchronising Users with User Points. But do not do this now.  Please first read the notes below.

User Points00F


The first thing to do with User Points is to click on the userPointsControlPanelButtonand then use the button options button which, in common with other Components, is located at the top righthand side of the  Control Panel.

Select the V4 tab general  as it allows setting the format of the points, and whether accounts are allowed to go negative.

User Points00D

Allowing negative accounts is generally a poor idea as it can lead to users being able to download multiple items at no cost!

Setting the default format is sensible if you are equating points to a financial charge.

Note that jDownloads only shows 2 decimal places with User Points items.
User Points actions are controlled by a set of Rules which give it a very wide variety of uses.

To access these click on the V4 button User Points control panelthen on V4 button rules02.

There are presently 15 basic rules in UserPoints.

To modify the rule parameters click on the Rule name.
 
UP rules01

One such User Points rule, New User, is the ability to give new users some 'points' initially. 

If you are going to give new users, that is your existing users when first installing User Points, some 'starter' points then that needs to be done before Synchronising Users.

Basically Synchronising Users means adding in all your existing users before User Points was installed. The process of Synchonising Users is dealt with later in this article.

After installation of User Points any new user you add will be included automatically in User Points.
UP00C

Give New User 'starter' points

In order to give new users an initial grant of starter points then it is necessary to edit the appropriate rule.

To do this select the V4 button control panel and click on the on either V4 button rules02or  V4 button rules.
There are 15 rules initially.   Note that most of the rules are initially unpublished.

Note that from jD4.0.40 and above the jD Rules are added automatically so there will be 20 rules. For earlier versions adding the five more jDownloads specific rules is descibed later in the 'Adding Rules' section.

Scroll down the list of rules, and possibly change to the next set, until you find the 'New User' Rule as illustrated below.  Make sure it is Published, that is it shows the User Points published icon User Points 69.  If it shows 'Unpublished' UP 69A then click on the icon to change status to published.
User Points00B

Next click on the New User link which brings up the the details section of the New User rule such as shown opposite.

So if you are going to give all new users a starter number of points then edit the Points field as appropriate, say set to 5.00 as a 'welcome'.

Note this field has two decimal places like most "currencies".

After Saving & Closing ensure that the Rule is published, that is it has a published symbol, published symbol.  If it is not published, unpuplisished symbol, then click on the symbol.
User Points00C

Syncronising Users

If you have not previously used User Points then it will not know about the regular Joomla! users you may already have 'registered' on your site. 

Go back to the V4 button User Points control panel and click on the User Points Users Icon User Points 72.  This shows that at this stage User Points does not know about existing users as illustrated below.
User Points 32B
The next step is to Synchronise the Users, that is adding all existing users of Joomla into the User Points scheme.
To do this return to the User Points Control panel and click on the 'User Sync' icon.  User Points 71 A message saying 'This may take several minutes....' may be displayed depending on how many users are already 'registered' on your site.  In due course it should give a successful completion statement. 
Clicking on the Users icon User Points 72 again will now show something like the view opposite.  Note in this case the 'New User' rule had been set to 5.00 points before synchronising new users. User Points 32C

Any new user added to Joomla! after User Points has been activated will be automatically added and granted an initial stock of points as set up in the New User rule.

Give Users Bonus Points

There are a variety of ways to give users points.  One simple method is to add 'Bonus' points after setting some value, 3.00 in this example, in the Bonus rule as shown opposite.
V4 add bonus01
To give bonus Points to a user goto the V4 button userslist and select the users by clicking on the 'tick' box. Then click on the V4 button bonus button at the top of the view.
V4 add bonus02
If you click on V4 button userslist again it shows that user jdx46-uploader now has 7.30 points. You may of course select multiple users.
V4 add bonus03

Adding jD Rules

This section only applies if you are using jD4.0.39 or earlier
Before adding the specific jDownloads rules  you must have enabled use of User Points as noted earlier in  jDownloads setup for User Points.

In jDownloads 4.0.40 and above the User Points rules specific to jD are already incuded within the code. So there is no need to download any plugins or similar from jdownloads.com

The next step is to activate the jD specific Rules.  This is also very straight forward. 
Basically one just clicks on the 'Auto-detect new rules'  button User Points 73 on the User Points Control Panel.  This should give you a message acknowledging that five more rules have been added User Points 61
NOTE: There is no external plugin to be enabled as the relevant code is in the jD Component.

Setting Up jD Rules


The five jD specific Rules need to be setup.  So click on the Rules icon button  User Points 74 then on the Category pulldown , which is near the top left as illustrated immediately opposite, select the 'Other' type in the pulldown as illustrated on the far rigt image opposite.h
 
This then just lists the Rules in the 'Other' section, which is where the five jD rules are located.  So scroll down to find the jD specific rules.

Click on the name part of the rule to access the details.

The jD specific rules are noted below
category pulldown02User Points 75A
  • User Upload published Assign points to a user when one of their uploads is published in jDownloads (may also be negative to reduce points).  Access Rule and set points value.
  • User downloads a file  Deduct points when a registered user downloads a file from jDownloads . Access the Rule to set how many points the Download will cost.
  • User downloads a file (uses price) Uses the value in the 'price' field in the Download. Deducts the points specified in the Price Field of the Download when a registered user downloads a file from jDownloads. Also see note below about Download Managers.
  • Uploader get points for downloaded files Assign points to the file uploader when a user downloads this file from jDownloads. Uses a fixed number of points as defined in this rule.  Access the rule to set the value.
  • Uploader get points for downloaded files (use price) Assign points to the file uploader when a user downloads the file from jDownloads. Uses the 'price' field from the Download.

There are numerous parameters that may be set up in each rule.  For a full understanding consult the User Points documentation.

However in most cases the only part that needs to be adjusted is the Price field. 

As an exampe the image opposite shows part of the User downloads a file rule. 
User Points rule
One other parameter which may be useful is the 'Method' parameter.  Here you can set up a time period such as 'once per year'.  This would mean the user would only be charge initially on first download but could then download multiple times throughout the year.  Basically a warranty period with access to updates.

Using a Download Manager


If you are using a download manager on your local machine then you might find that multiple 'charges' are being made against the user points. 

This is because many 'download managers' open multiple 'streams'.   Unless you set thing up in an appropriate manner then each 'stream' appears as if it were a fresh downloading of the original file. 

Hence there is a danger of multiple download charges! 

The solution is to change the Method field of the User downloads a file (uses price) rule so that the user is only charged once/day for downloading that file, or another appropriate selection, such as illustrated below. 

UserPoints14A
Note the 'charge once/day' attribute is applicable to each download individually. 

That is if a user makes multiple downloads of the same Download they will only be charged once that day for that Download.

If that user downloads another Download then they will be charged for the second Download.  If the user downloads multiple times in the selected period then these do not create an User Points event.

Other options include 'once per user' meaning that file is free for that user forever after.  Further choices include once/week, once/month and once/year.  This period could be the duration of free updates after the initial purchase.

Example


When you get to the Summary view, there is now an additional message "This Download costs 1.70 points. You currently have 5 points."

As we have sufficient points then the download can proceed.
example01

When you do not have suficient points Then a message appears advising you about the situation as illustrated opposite. 

There is of course no Download button.


example02

Updating UserPoints

Get update key

There are two stages, the first is getting your personal update Key - this Stage is a one time activity.
The key is located in UserPoints profile on the Remository web site.
The second Stage is the usual Joomla update.
 So after logging in to Remository, the Main Menu will show 'My Account' as illustrated in the first image opposite.
Click on Profile.
This will then show your personal update server key - which is in this example is partially blocked out! Use Cntl-V or similar to take a copy  of the key.
V4 profile02V4 profile03
Next  click on the UserPoints button AUP control panel.  Next click on thebutton optionsbutton which is at top right.

Then in the General tab copy your personal key into the Update Key field as illustrated opposite. 
V4 profile05

UserPoints Update

Click on the V4 button system button then in the V4 update section section wait a while Joomla searches if there are any Extension updates outstanding.

In this example there is one extension that has an outstanding Extension update available.

V4 update01
Click on V4 button update extensions which in this example shows that there is an updated version of UserPoints.

So click on the tick and then on the link as indicated opposite.
V4 update02
Then click on the V4 update03 button, which, if all is OK, will give a message such as shown opposite.
V4 update04
Joomla only checks for updates periodically, so if no update is indicated then as a double check click on V4 button update extensions button.
This will take you to the Check for Updates page as indicated opposite.

So click on V4 button check for updates Button.
V4 check for updates01

Appendix - Uninstalling User Points

To uninstall all of UserPoints then, like jDownloads, just uninstall the Component.
First click on V4 button system, then in the V4 button manage tab section click on the V4 button Extensions.  Then in the Search field enter userpoints as shown below and click on the search button.
V4 userpoints searchThis shows a view as illustrated opposite.
UserPoints Uninstall01
1.Select the component
2.Click on the V4 button uninstall inactive button which turns red V4 button uninstall when you hover over it.

After accepting an 'Are you sure' message, all parts of UserPoints, except the database, will be uninstalled.
uninstall done message

Appendix - User Points for Joomla 3

The original User Points developers, Alphauserpoints, are no longer active.

A free Joomla V3 version of AltaUserPoints is supported by Nordmograph who are specialist Joomla Extension Suppliers,  www.nordmograph.com/extensions/  (opens in a new window/tab). There is a Tag Cloud on the page so click on either click on the FREE or the ALTAUSERPOINTS tag.  Nordmograph also have some free and paid extensions for extra User Points facilities if you should wish to use elsewhere.

An alternative and simpler methodto get AltaUserPoints for Joomla 3 by Nordmograph is to use the Joomla Extensions Directory (JED) at http://extensions.joomla.org/extensions/extension/e-commerce/credits-a-point-systems/altauserpoints (opens in a new window/tab). Nordmograph do not have a Joomla 4 version.

Changing to UserPoints in Joomla 4 and above

The actual change is really simple because:
  1. AltaUserPoints, Alppha UserPoints and User Points all use the same database structure;
  2. Also they do not remove the database tables when they are uninstalled.
The procedure is:
  1. Make a site backup just in case!
  2. Uninstall Alpha/Alta user Points whilst still on Joomla 3 as below
    1. Go to Joomla! Extensions - Manage, and then select Manage on the pulldown.
    2. Search for Alpha, which will list the AlphaUserPoints Component and several plugins and modules.
    3. Select All and then Uninstall.  You should get messages for the component uninstall and for multiple plugin and module uninstalls.
  3. Now convert to Joomla 4/5.
  4. Use normal sequence to install UserPoints, this will pick up the previous entries from the database.

ColinM Rewritten September 2019 updated August 2021, restructured July 2023, revisedV4 January 2024, March 2024, June 2024

Print Email

We use cookies

We use cookies on our website. Some of them are essential for the operation of the site, while others help us to improve this site and the user experience (tracking cookies). You can decide for yourself whether you want to allow cookies or not. Please note that if you reject them, you may not be able to use all the functionalities of the site.