AltaUserPoints Developers API documentation

Introduction AltaUserPoints - API integration in a Third party component (advanced)

This documentation is priorly dedicated to developers and anyone with a sufficient knowledge of PHP language and Joomla! components development.
Licence: AltaUserPoints is released under license GNU/GPL License. Author: Bernard Gilly – Adrien Roussel - This project started as AltaUserPoints back in 2008.

Plugin/Rule creation

A plugin creation (new rule creation for a 3rd party component) is done in 2 steps

Step1 - API insertion in a component

Just insert the following API in the component code where needed. The best is to make it follow a user action that could give the users some points or take some. For example : in a comment system component or in a forum, just add the API after the comment or topic INSERT query in the database.

Basic API 

$api_AUP = JPATH_SITE.'/components/com_altauserpoints/helper.php';
if ( file_exists($api_AUP))
{
require_once $api_AUP;
AltaUserPointsHelper::newpoints( 'function_name' );
}


function_name is the name of the rule that will be used to attribute points to the current user (if logged in). For each AltaUserPoints integrated rule (system rules), names syntax is as follows: 

example: sysplgaup_newregistered for new users points attribution

It is convenient to keep the same name syntax for third party components plugin as follows:

plgaup_functionname

Example: plgaup_newcomment or plgaup_newtopic for a comment system or forum API integration. To name a rule that would give points when adding a new topic in Kunena: plgaup_kunena_topic_create.

Keep in mind that this method only gives points to the current user logged in. This is the Basic API.

Attribute points to another user than the current user

To give points to anothe user than the one connected, only the user id is required. To get his AltaUserPoints (AUPID) Identity, we just need to use the getAnyUserReferreID(). This method is the one used to give points to an article author when the article is being read by someone on the site.

$api_AUP = JPATH_SITE.'/components/com_altauserpoints/helper.php';
if ( file_exists($api_AUP))
{
require_once $api_AUP;
$aupid = AltaUserPointsHelper::getAnyUserReferreID( $userID );
if ( $aupid )
AltaUserPointsHelper::newpoints( 'function_name', $aupid );
}
 

Prevent from attributing points more than once for the same action

To avoid that a user would get points many times for something allready done, we can add a reference key. When calling the AltaUserPointsHelper::newpoints function, a pre check is done on this reference key. This method is used in the rule where a user reading an article would give points to the author.

$api_AUP = JPATH_SITE.'/components/com_altauserpoints/helper.php';
if ( file_exists($api_AUP))
{
require_once $api_AUP;
$keyreference = AltaUserPointsHelper::buildKeyreference('function_name', ‘item id’ );
AltaUserPointsHelper::newpoints( 'function_name', '', $keyreference);
}



Adding information datas

To add information datas to be displayed in the action details, just add a new parameter as follows:  

$api_AUP = JPATH_SITE.'/components/com_altauserpoints/helper.php';
if ( file_exists($api_AUP))
{
require_once $api_AUP;
$keyreference = AltaUserPointsHelper::buildKeyreference('function_name', ‘item id’ );
AltaUserPointsHelper::newpoints( function_name','', $keyreference,'information_datas');
}
 

Using different amounts of points on the same rule

A component might also need to add or to take points for different amounts. For example, when buying goods with points. Products have different prices, a fixed amount in the rule would'nt make it. The API $randompoints parameter comes instead of the amount of points set in the rule. It can be negative in case of purchases or penalities.

$api_AUP = JPATH_SITE.'/components/com_altauserpoints/helper.php';
if ( file_exists($api_AUP))
{
require_once $api_AUP;
$keyreference = AltaUserPointsHelper::buildKeyreference('function_name', ‘item id’ );
AltaUserPointsHelper::newpoints( function_name','', $keyreference,'',-1450);
}
 

Get the result from a successfull operation

In a more advanced code, if the component routine needs to know if the operation has been successfull or not, (enough amount of points for a purchase in a user account), we can add a 'feedback' parameter. It has a Boolean type value. Code example:

$api_AUP = JPATH_SITE.'/components/com_altauserpoints/helper.php';
if ( file_exists($api_AUP))
{
require_once $api_AUP;
$keyreference=AltaUserPointsHelper::buildKeyreference('plgaup_purchasewithvirtuemart', $transactionID );
if (AltaUserPointsHelper::newpoints( 'plgaup_purchasewithvirtuemart', '', $keyreference, 'Product reference: AM-5245', -1290, true))
{
[... code continued...]
}
}
 

Remove the constraint on the type of user

In a customized code component, you can force and remove the constraint on a rule to the user level by adding the parameter force = 1. The existing rule will be available now for guest, registered and special

Display an additional system message on frontend

you can display a specific message on frontend by adding the parameter frontmessage=”You custom message”. API full implementation  

AltaUserPointsHelper::newpoints(
string$pluginfunction,
[string$AUPIDotheruser = ''],
[string$keyreference = ''],
[string$data = ''],
[integer$randompoints = 0],
[boolean$feedback = false],
[integer$force=0],
[string$frontmessage='']
);


Note: If the operation is a points substraction, the account has to have at least the same amount of points. If not, a notice warns the user that he doe'snt have enough points to complete the action (by default). You can set up general parameter in the configuration of AltaUserPoints, in backend administrator to allows your users to have a negative account.

Step 2 - XML file creation

Then developers have to create an xml file to make easier the installation process in the AltaUserPoints component. This xml file has to be utf-8 encoded (required). All developers of third party extensions for Joomla! can add directly at the root of their frontend component a unique xml file containing all the rules for a single component. Deveoper has to respect the ordering and tags: structure example: altauserpoints_rule.xml Tag “component” is the name of the third component like “com_kunena” or other. As it is the same component, it is worth repeating for each rule in the tag “rule”.
Administrator of the website which install a third component with this xml file can autodetect directly from the button “auto-detect plugins” in control panel of AltaUserPoints.
This xml file has to be utf-8 encoded (required) but not be zipped! Just put this file at the root of frontend component folder or plugin or module and include this file in your installer extension. This file must be named exactly as follows: altauserpoints_rule.xml

Code list for categories :

ar -> articles
cd -> coupons
co -> community
fo -> forums/comments
li -> links
mu -> music
ot -> other
ph -> photo
po -> polls
pu -> purchase
re -> recommend/send to a friend
sh -> shopping
su -> private
sy -> system rules
us -> users
vi -> video

NOTE : Optionally, you can avoid this step manually by filling all the fields in the creation of a new rule directly in the rule manager (button 'New' in toolbar). 

Plugin/Rule installation

- auto-detect xml file at the root of frontend component:
Click on the button “Auto-detect plugins” in the control panel of AltaUserPoints after installation of third component, plugin or module. Check regularly or periodically by clicking on this button.

Using AltaUserPoints informations in a third party component

You can use easily the profil informations of a user directly in a third component.
=> Before using a function, you must include the API at least once in your page like this:

$api_AUP = JPATH_SITE.'/components/com_altauserpoints/helper.php';
if ( file_exists($api_AUP)) { require_once $api_AUP; }

Profil informations

To get the entire profil information, just use the function getUserInfo();
Just use the referreid of AltaUserPoints user or the joomla ID of the user (Id of Joomla users table).

Use the first method with the referreid to get user Information profile like this :

AltaUserPointsHelper::getUserInfo($referrerid );


If you do not have the referreid, you can use the ID of user in second parameter like this :

$user = JFactory::getUser();
$userid = $user->id ;
$profil = AltaUserPointsHelper::getUserInfo ( '', $user->id );


Then you can get the following user informations:
$profil->name
$profil->username
$profil->registerDate
$profil->lastvisitDate
$profil->email
$profil->referreid
$profil->points
$profil->max_points
$profil->last_update
$profil->referraluser
$profil->referrees
$profil->blocked
$profil->birthdate
$profil->avatar
$profil->levelrank
$profil->leveldate
$profil->gender
$profil->aboutme
$profil->website
$profil->phonehome
$profil->phonemobile
$profil->address
$profil->zipcode
$profil->city
$profil->country
$profil->education
$profil->graduationyear
$profil->job
$profil->facebook
$profil->twitter
$profil->icq
$profil->aim
$profil->yim
$profil->msn
$profil->skype
$profil->gtalk
$profil->xfire
$profil->profileviews 

Get AUP avatar of user

Display the image of avatar from AltaUserPoints.

$avatar = AltaUserPointsHelper:: getAupAvatar(
$userid,
[$linktoprofil=0],
[ $width=48],
[$height=48],
[$class=''],
[$otherprofileurl='']
)
echo $avatar ;


if $linktoprofil set to 1, display avatar with the link to the AUP profil of this user.

Get link to AUP user profil

Get the url to show the profil of user.

$linktoAUPprofil = AltaUserPointsHelper::getAupLinkToProfil($userid);

Get link to AUP users list

Get the url to show the list of users with points etc…

$linktoAUPusersList = AltaUserPointsHelper:: getAupUsersURL();


Get avatar Path of a user

Get the path avatar path of a specific user

$avatarPath = AltaUserPointsHelper:: getAvatarPath( $userid );


Get avatar Live Path of a user

Get the live url avatar path of a specific user

$avatarLivePath = AltaUserPointsHelper:: getAvatarLivePath( $userid );


Get the medals list of a user

$medalslistuser = getUserMedals($referrerid);
or
$medalslistuser = getUserMedals('', $userid);

return $medallistuser->id
return $medallistuser->rank (name of medal)
return $medallistuser->description (reason for awarded)
return $medallistuser->icon (name file icon)
return $medallistuser->image (name file image) Complete example to display large image of medals:

$user = JFactory::getUser();
$userid = $user->id ;
if(!defined("_AUP_MEDALS_PATH"))
{
define('_AUP_MEDALS_PATH', JURI::root() . 'components/com_altauserpoints/assets/images/awards/large/’);
}
if(!defined("_AUP_MEDALS_LIVE_PATH"))
{
define('_AUP_ MEDALS _LIVE_PATH', JURI::base(true) . '/components/com_altauserpoints/assets/images/awards /large/');
}
$medalslistuser = AltaUserPointsHelper::getUserMedals( '', $userid );
for each ( $medalslistuser as $medallistuser )
{
echo '<img src="'. _AUP_MEDALS_LIVE_PATH'.$medallistuser->image . '" alt="" />';
}


Get the ReferreID of any user

$referreid = AltaUserPointsHelper::getAnyUserReferreID( $userID );



Get the current total points of any user

Use the first method with the referreid to get the total of points

$totalPoints = AltaUserPointsHelper::getCurrentTotalPoints( $referrerid );

If you have not the referreid, you can use the ID of user (joomla) in second parameter like this :

$user = JFactory::getUser();
$userid = $user->id ;
$totalPoints = AltaUserPointsHelper::getCurrentTotalPoints( '', $userid );


Get the list of activities

$listActivities = AltaUserPointsHelper::getListActivity($type='all', $userid='all', $numrows=0);

$params $type = all | positive | negative
$params $userid = all or unique userID
$params $limit = int (0 by default)
example-1 -> -------------------------------------------------------------------------
example-1 -> $listActivities = AltaUserPointsHelper::getListActivity('all', 'all');
example-1 SAME AS -> $listActivities = AltaUserPointsHelper::getListActivity();
example-1 -> show all activities with pagination, positive and negative points of activity for all users
-----------------------------------------------------------------------------------
example-2 -> -------------------------------------------------------------------------
example-2 -> $user = JFactory::getUser();
example-2 -> $userID = $user->id;
example-2 -> $listActivities = AltaUserPointsHelper::getListActivity('positive',$userID,20);
example-2 -> show only positive points of activity for the current user logged in and show only 20 rows of recent activities

Returns an array or $rows
List of available fields :
insert_date
referreid
points (of this activity)
datareference
rule_name
plugin_function
category

Get the next user rank

$nextrankinfo = AltaUserPointsHelper::getNextUserRank($referrerid='’, $userid='0', currentrank);

return $nextrankinfo->id
return $nextrankinfo->rank (name of rank)
return $nextrankinfo->description (description of rank)
return $nextrankinfo->levelpoints (level points to reach this rank)
return $nextrankinfo->typerank (return 0)
return $nextrankinfo->icon (name file icon)
return $nextrankinfo->image (name file image)

Get version of AUP

$num_aup_version = AltaUserPointsHelper::getAupVersion();

Returns the current version of AltaUserPoints like -> 1.0.0



AltaUserPoints is open for third component

Create your own plugin for AltaUserPoint !
Plugins provide functions which are associated with trigger events.

Available events in AltaUserPoints:

- onBeforeInsertUserActivityAltaUserPoints - onUpdateAltaUserPoints
- onAfterUpdateAltaUserPoints
- onChangeLevelAltaUserPoints
- onUnlockMedalAltaUserPoints
- onGetNewRankAltaUserPoints
- onResetGeneralPointsAltaUserPoints
- onBeforeDeleteUserActivityAltaUserPoints
- onAfterDeleteUserActivityAltaUserPoints
- onBeforeDeleteAllUserActivitiesAltaUserPoints
- onAfterDeleteAllUserActivitiesAltaUserPoints
- onBeforeMakeRaffleAltaUserPoints
- onAfterMakeRaffleAltaUserPoints

You can see the example file /plugins/altauserpoints/example_plugin_aup.php in your Joomla directory with parameters for each functions.

jGifts Virtual Gifts component installation and setup

Jgifts Virtual Gifts for Joomla is a great extension to improve and optimise social relationships within your Joomla Community. Users spend points to gift each other with virtual gifts (beer, hugs, cakes , good luck items... ).
Before we get more indetails, let's have a look at the requirements and the installation process.

I - Requirements

Make sure the requirments are reached before installing jgifts, or reinstall when done.

0. Joomla 3+ is required

1. Profile manager application

jgifts component is a social application , it requires a profile manager component. Received (and approved) gifts are listed in users user profile. jGifts integrates with the 3 most popular profila managers and social networ extensions for Joomla.

  • Community Builder - This one is free but has all the required elements for jgifts. www.joomlapolis.com
  • Jomsocial - Commercial extension that provides all you need to buil a private social network. www.jomsocial.com
  • EasySocial - Commercial extension that provides all you need to buil an advanced private social network www.stackideas.com/easysocial
Note: In a close future jgifts may integrate an Activity Stream announcement feature. This is best supported by Jomsocial and easySocial

To gift eachother , users will spend userpoints

2. User Points manager extension

Users spend points to gift each others, but this is not the only transaction found in jgifts. The component can also be used as a Virtual gifts market place, where users can add / create their own gifts. When Gift addition is approved, gift creator earn a percentage comission in points when the gift is purchased by other users.

Make sure you have one of these User Points manager extension before you install jgifts. Jgifts will look for these to install the required points rules during installation process.

  • AltaUserPoints - Free advanced Userpoints manager www.nordmograph.com/extensions
  • Jomsocial - has a builtin rather limited but sufficient UserPoints feature
  • EasySocial - has a builtin rather limited but sufficient UserPoints feature


After you have installed your profile and userpoints managers, you can now install jGifts Virtual Gifts component for Joomla.

II - Installing the com_jigifts-X.X.zip archive

After your purchase you downloaded com_jgifts_UNZIPFIRST_zip archive. Make sure you extract its content to a folder. Browse this folder and find com_jgifts-X.X.zip (where X.X is the version number). Don't unzip this one.
Visit your Joomla Backend and go to the Joomla installer:

Main menu -> Extensions -> Manage -> Install

Select the UPLOAD PACKAGE FILE tab and click the 'Select file' button. Browse your computer and get to the folder where you previously unzipped com_jgifts_UNZIPFIRST_zip. Select com_jgifts-X.X.zip and click the 'Upload & Install' button.

The component comes with a script that will perform additional processes during the component installation:

- Automatic installation and enabling of the system plugin: plg_system_jgifts_notify. This plugin is responsible for notifying users when someone sent them a gift that needs approval before it is listed in user profile apps showing received gifts.
- Check for existence of a User points manager extension and installation of specific userpoints rules for gift purchase and points commission on gift sells.
- Creation of the first default jgifts category
- Creation of a first example gift
- First gift sent to admin as a workflow example.

III - Installing the jGifts profile application


When installation is complete you need to install the profile plugin available in the com_jgifts_UNZIPFIRST.zip 'Addons' folder.
Make sure you selec the correct one for your profile manager component.

plg_community_jgifts.zip for Jomsocial installs using the same Joomla extensions installer page as the component.
- plg_app_user_jgifts.zip for EasySocial install via the EasySocial applications installer.
- plug_cbjgifts.zip for Community Builder installs via the CB plugins installer page.

Don't try to install these 2 last ones via the Joomla installer, it won't work and you'll get a missing XML file error.

Finally you should install the plg_user_jgifts.zip from the provided Addons folder. This one install via the core Joomla installer and is responsible for removing gifting activities and / or added gifts, when a user is deleted from your sytem.

When done installing you may click the large jGifts options button or visit the jGifts backend : Main Menu -> Global configuration -> jGfts (administrator/index.php?option=com_config&view=component&component=com_jgifts)

jGifts Virtual Gifts component Settings

Now component and related extension are installed, we can focus on settings.

In the backend, component provides site admin with 3 main pages + config pages :
- Gifts manager (gifts list + Gift addition / edition form)
- Gifts categories manager (categories tree and category edition form)
- Gift activities (list of gifts that have been gifted to some users)
+ Main configuration options

In the front end, the component comes with various menu items you can set to let users access jGifts features. 
- Go to the Joomla administration and select MENUS -> [choose an existing menu] -> ADD NEW MENU ITEM
- In the Menu Item Type field, select the jGIFTS group and select a menu item type :
  • Gifts list with search and filter to let users browse available gifts and access the gift action form to offer a gift to another user spending points.
  • My Pending gifts list to let users manage their receved gifts that are still pending , waiting for approval.
  • Gift form to let users add gifts from the front end (optional)

I - Component Main configuration

BACKEND MAIN MENU -> SYSTEM -> GLOBAL CONFIGURATION -> JGIFTS

Parameters:

Profile Manager: jGifts can be used without, but it is recommended to choose between Community Builder (Free), Jomsocial and EasySocial as profile manager. These will allow users to have their received gifts listed on their profile.
Note for EasySocial users: There are 2 alert notifications to be discovered via your EasySocial Alerts manager.

Point System: jGifts requires users to have points to spend to send gifts. A pointsystem is required. Install either AltaUserPoints (free), Jomsocial or EasySocial as points system BEFORE installing jgifts. "Before" because it will allow jgifts to identify automatically your Points system during installation and install the required points rules (for Gift purchase and sells commissions) accordingly.

Creator Commission Percentage: In case you allow users to add gifts using the front end, you can reward them with points as their added gift becomes popular. You can set a percentage commission on sells.

Show Category: If you have only one category, you can disable this information to show on gift thumbnail.

Show Creator: If you don't allow users to add their own gifts, you can disable this information to show on gift thumbnail. 

Naming: naming format, choose between username or name

Gift Name Limit: Limit the gift title length (server side)

Max File Size: Front end Limit of the gift picture size

Description limit: Front end limit for the gift's description length

Maximum Message Size: Limit the message length when user is filling the form to gift someone

Autopublish: Autopublish front end submission. Disable this and enable following Email FE submission to moderate front end submissions.

Emaill FE submission: Enable this to receive notifications for front end gifts submissions

Emaill Address: set the email to received notifications for front end gifts submissions

Note about the frontend submission moderation flow
Registered user can add a gift using the front end ADD GIFT form menu item.
When form is submitted (Autopublish setting disabled), gift is added unpublished, only visible from the backend. A notification email is sent to specified email address. Email body message conatains a link to the gift form in jgifts backend. Once the gift is published, gift creator receives a confirmation email with a frontend link to the published gift.
Disclaimer: Nordmograph is not affiliated with or endorsed by The Joomla! Project™. Any products and services provided through this site are not supported or warrantied by The Joomla! Project or Open Source Matters, Inc. Use of the Joomla!® name, symbol, logo and related trademarks is permitted under a limited license granted by Open Source Matters, Inc.