userpoints:developer
Differences
This shows you the differences between two versions of the page.
Next revision | Previous revision | ||
userpoints:developer [2023/05/02 14:05] – created admin | userpoints:developer [2025/03/07 14:28] (current) – admin | ||
---|---|---|---|
Line 1: | Line 1: | ||
- | ====== | + | ====== |
- | Introduction BetaUserPoints - API integration in a Third party component (advanced) | + | This is an introduction to UserPoints integrations with Joomla or third party extensions. It is dedicated to developers and anyone with a sufficient knowledge of the PHP language and Joomla 4/5 extension development. There is a UserPoints API which has recently been simplified. |
- | This documentation is dedicated to developers and anyone with a sufficient knowledge of the PHP language and Joomla 4 component development. | + | Licence: |
- | Licence: | + | |
- | ===== Plugin/Rule creation | + | ===== Basic Operation of UserPoints |
- | A plugin creation (new rule creation | + | UserPoints provides a way to award users points |
+ | The handling of points is determined by what are called **rules** in UserPoints. A rule is triggered by something happening as a result of user action. The rule determines what happens in the way of awarding or deducting points. UserPoints automatically installs some plugins and rules that support actions triggered by standard Joomla extensions. These include actions to do with content (articles) and to do with user registration. | ||
- | === Step1 - API insertion in a component === | + | Unfortunately, |
- | Just insert | + | ===== Ways to Connect Software to UserPoints ===== |
+ | |||
+ | The approach is different, depending on whether | ||
+ | |||
+ | Alternatively, | ||
=== Basic API === | === Basic API === | ||
+ | The UserPoints code has been fully namespaced and will autoload when used correctly. In addition, for Joomla 3.x, UserPoints automatically installs and enables a plugin that will establish the namespacing. This is not necessary with Joomla 4+ which takes account of the namespace in the UserPoints packaging XML. | ||
+ | |||
+ | Given the above, use of the API becomes in its simplest form: | ||
<code php> | <code php> | ||
- | | + | |
- | if ( file_exists($api_BUP)) | + | if (class_exists(UserPoints:: |
- | | + | |
- | | + | |
} | } | ||
</ | </ | ||
- | function_name | + | rule_name |
example: sysplgbup_newregistered for new users points attribution | example: sysplgbup_newregistered for new users points attribution | ||
- | It is convenient to keep the same name syntax | + | You should select names for rules that are unlikely to conflict with other integrations. |
- | + | ||
- | plgbup_functionname | + | |
- | + | ||
- | Example: plgbup_newcomment or plgbup_newtopic for a comment system or forum API integration. To name a rule that would give points when adding a new topic in Kunena: plgbup_kunena_topic_create. | + | |
Keep in mind that this method only gives points to the current user logged in. This is the Basic API. | Keep in mind that this method only gives points to the current user logged in. This is the Basic API. | ||
Line 42: | Line 44: | ||
=== Attribute points to another user than the current user === | === Attribute points to another user than the current user === | ||
- | To give points to anothe | + | To give points to another |
<code php> | <code php> | ||
- | | + | |
- | if ( file_exists($api_BUP)) | + | if (class_exists(UserPoints:: |
- | | + | $upid = UserPoints:: |
- | | + | if ( $bupid ) UserPoints:: |
- | $bupid | + | |
- | if ( $bupid ) BetaUserPointsHelper:: | + | |
} | } | ||
</ | </ | ||
Line 56: | Line 56: | ||
=== Avoid attributing points more than once for the same action === | === Avoid attributing points more than once for the same action === | ||
- | To avoid a user getting points many times for something already done, we can add a reference key. When calling the BetaUserPointsHelper::newpoints function, a precheck 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. | + | To avoid a user getting points many times for something already done, we can add a reference key. When calling the UserPoints::newpoints function, a precheck 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. |
<code php> | <code php> | ||
- | | + | |
- | if ( file_exists($api_BUP)) | + | if (class_exists(UserPoints:: |
- | | + | $keyreference = UserPoints:: |
- | require_once $api_BUP; | + | |
- | $keyreference = BetaUserPointsHelper:: | + | |
- | | + | |
} | } | ||
</ | </ | ||
- | === Adding information | + | === Adding information |
- | To add information | + | To add information |
<code php> | <code php> | ||
- | | + | |
- | if ( file_exists($api_BUP)) | + | if (class_exists(UserPoints:: |
- | | + | $keyreference = UserPoints:: |
- | require_once $api_BUP; | + | |
- | $keyreference = BetaUserPointsHelper:: | + | |
- | | + | |
} | } | ||
</ | </ | ||
Line 84: | Line 80: | ||
=== Using different amounts of points on the same rule === | === 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. | + | 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 not work. 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. |
<code php> | <code php> | ||
- | | + | |
- | if ( file_exists($api_BUP)) | + | if (class_exists(UserPoints:: |
- | | + | $keyreference = UserPoints:: |
- | require_once $api_BUP; | + | |
- | $keyreference = BetaUserPointsHelper:: | + | |
- | | + | |
} | } | ||
</ | </ | ||
Line 98: | Line 92: | ||
=== Get the result from a successful operation === | === Get the result from a successful operation === | ||
- | In a more advanced code, if the component routine | + | In more advanced code, if the new software |
<code php> | <code php> | ||
- | | + | |
- | if ( file_exists($api_BUP)) | + | if (class_exists(UserPoints:: |
- | | + | $keyreference=UserPoints:: |
- | require_once $api_BUP; | + | if (UserPoints:: |
- | $keyreference=BetaUserPointsHelper:: | + | |
- | if (BetaUserPointsHelper:: | + | |
{ | { | ||
- | [... code continued | + | [... code for successful operation |
} | } | ||
} | } | ||
Line 117: | Line 109: | ||
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_. | 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 | + | === Display an additional system message |
- | you can display a specific message | + | you can display a specific message |
<code php> | <code php> | ||
- | | + | |
- | string$pluginfunction, | + | if (class_exists(UserPoints:: |
- | [string$BUPIDotheruser = '' | + | UserPoints:: |
- | [string$keyreference = '' | + | string $pluginfunction, |
- | [string$data = '' | + | [string $BUPIDotheruser = '' |
- | [integer$randompoints = 0], | + | [string $keyreference = '' |
- | [boolean$feedback = false], | + | [string $data = '' |
- | [integer$force=0], | + | [integer $randompoints = 0], |
- | [string$frontmessage='' | + | [boolean $feedback = false], |
- | ); | + | [integer $force=0], |
+ | [string $frontmessage='' | ||
+ | ); | ||
+ | } | ||
</ | </ | ||
- | Note: If the operation is a points substraction, | + | Note: If the operation is a points substraction, |
==== Step 2 - XML file creation ==== | ==== Step 2 - XML file creation ==== | ||
- | Then developers have to create an xml file to make easier the installation process in the BetaUserPoints component. This xml file has to be utf-8 encoded | + | To complete the integration of an application with UserPoints, |
- | Administrator of the website which install a third component | + | |
- | This xml file has to be utf-8 encoded (required) but not be zipped! Just put this file at the root of frontend | + | An example of userpoints_rule.xml is the file for Remository which reads: |
+ | |||
+ | < | ||
+ | <?xml version=" | ||
+ | < | ||
+ | <component> | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | </ | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | </ | ||
+ | </ | ||
+ | </ | ||
+ | </ | ||
=== Code list for categories : === | === Code list for categories : === | ||
Line 163: | Line 186: | ||
</ | </ | ||
- | 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 ' | + | === Code list for methods: === |
+ | |||
+ | You can add a < | ||
+ | |||
+ | < | ||
+ | 1 -> Only once | ||
+ | 2 -> Once a day per user | ||
+ | 3 -> Once a day for a single user on all users | ||
+ | 4 -> Whenever | ||
+ | 5 -> Once per week | ||
+ | 6 -> Once per month | ||
+ | 7 -> Once per year | ||
+ | </ | ||
- | ==== Plugin/Rule installation ==== | + | NOTE : It is possible to create new rules manually by filling all the fields in the creation of a new rule directly in the rule manager (button ' |
- | - auto-detect xml file at the root of frontend component: | ||
- | Click on the button “Auto-detect plugins” in the control panel of BetaUserPoints after installation of third component, plugin or module. Check regularly or periodically by clicking on this button. | ||
- | ==== Using BetaUserPoints | + | ===== Using UserPoints |
You can use easily the profil informations of a user directly in a third component. | You can use easily the profil informations of a user directly in a third component. | ||
Line 176: | Line 210: | ||
<code php> | <code php> | ||
- | $api_BUP | + | $api_UP |
</ | </ | ||
Line 182: | Line 216: | ||
To get the entire profil information, | To get the entire profil information, | ||
- | Just use the referreid of BetaUserPoints | + | Just use the referreid of UserPoints |
Use the first method with the referreid to get user Information profile like this : | Use the first method with the referreid to get user Information profile like this : | ||
<code php> | <code php> | ||
- | BetaUserPointsHelper:: | + | UserPoints:: |
</ | </ | ||
Line 193: | Line 227: | ||
<code php> | <code php> | ||
- | $user = JFactory:: | + | $user = JFactory:: |
</ | </ | ||
Line 241: | Line 275: | ||
=== Get BUP avatar of user === | === Get BUP avatar of user === | ||
- | Display the image of avatar from BetaUserPoints. | + | Display the image of avatar from UserPoints. |
<code php> | <code php> | ||
- | $avatar = BetaUserPointsHelper:: getAupAvatar( $userid, [$linktoprofil=0], | + | $avatar = UserPoints:: getAupAvatar( $userid, [$linktoprofil=0], |
</ | </ | ||
Line 255: | Line 289: | ||
<code php> | <code php> | ||
- | $linktoBUPprofil = BetaUserPointsHelper:: | + | $linktoBUPprofil = UserPoints:: |
</ | </ | ||
Line 263: | Line 297: | ||
<code php> | <code php> | ||
- | $linktoBUPusersList = BetaUserPointsHelper:: getAupUsersURL(); | + | $linktoBUPusersList = UserPoints:: getAupUsersURL(); |
</ | </ | ||
Line 272: | Line 306: | ||
<code php> | <code php> | ||
- | $avatarPath = BetaUserPointsHelper:: getAvatarPath( $userid ); | + | $avatarPath = UserPoints:: getAvatarPath( $userid ); |
</ | </ | ||
Line 281: | Line 315: | ||
<code php> | <code php> | ||
- | $avatarLivePath = BetaUserPointsHelper:: getAvatarLivePath( $userid ); | + | $avatarLivePath = UserPoints:: getAvatarLivePath( $userid ); |
</ | </ | ||
Line 307: | Line 341: | ||
if(!defined(" | if(!defined(" | ||
{ | { | ||
- | define(' | + | define(' |
} | } | ||
if(!defined(" | if(!defined(" | ||
{ | { | ||
- | define(' | + | define(' |
} | } | ||
- | $medalslistuser = BetaUserPointsHelper:: | + | $medalslistuser = UserPoints:: |
for each ( $medalslistuser as $medallistuser ) | for each ( $medalslistuser as $medallistuser ) | ||
{ | { | ||
Line 323: | Line 357: | ||
<code php> | <code php> | ||
- | $referreid = BetaUserPointsHelper:: | + | $referreid = UserPoints:: |
</ | </ | ||
Line 334: | Line 368: | ||
<code php> | <code php> | ||
- | $totalPoints = BetaUserPointsHelper:: | + | $totalPoints = UserPoints:: |
</ | </ | ||
Line 340: | Line 374: | ||
<code php> | <code php> | ||
- | $user = JFactory:: | + | $user = JFactory:: |
</ | </ | ||
Line 346: | Line 380: | ||
<code php> | <code php> | ||
- | $listActivities = BetaUserPointsHelper:: | + | $listActivities = UserPoints:: |
</ | </ | ||
Line 354: | Line 388: | ||
$params $limit = int (0 by default) | $params $limit = int (0 by default) | ||
example-1 -> ------------------------------------------------------------------------- | example-1 -> ------------------------------------------------------------------------- | ||
- | example-1 -> $listActivities = BetaUserPointsHelper:: | + | example-1 -> $listActivities = UserPoints:: |
- | example-1 SAME AS -> $listActivities = BetaUserPointsHelper:: | + | example-1 SAME AS -> $listActivities = UserPoints:: |
example-1 -> show all activities with pagination, positive and negative points of activity for all users | example-1 -> show all activities with pagination, positive and negative points of activity for all users | ||
----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ||
Line 361: | Line 395: | ||
example-2 -> $user = JFactory:: | example-2 -> $user = JFactory:: | ||
example-2 -> $userID = $user-> | example-2 -> $userID = $user-> | ||
- | example-2 -> $listActivities = BetaUserPointsHelper:: | + | example-2 -> $listActivities = UserPoints:: |
example-2 -> show only positive points of activity for the current user logged in and show only 20 rows of recent activities | example-2 -> show only positive points of activity for the current user logged in and show only 20 rows of recent activities | ||
</ | </ | ||
Line 382: | Line 416: | ||
<code php> | <code php> | ||
- | $nextrankinfo = BetaUserPointsHelper:: | + | $nextrankinfo = UserPoints:: |
</ | </ | ||
Line 398: | Line 432: | ||
<code php> | <code php> | ||
- | $num_bup_version = BetaUserPointsHelper:: | + | $num_bup_version = UserPoints:: |
</ | </ | ||
- | Returns the current version of BetaUserPoints | + | Returns the current version of UserPoints |
- | ==== BetaUserPoints | + | ==== UserPoints |
- | Create your own plugin for BetaUserPoints | + | Create your own plugin for UserPoints |
Plugins provide functions which are associated with trigger events. | Plugins provide functions which are associated with trigger events. | ||
- | Available events in BetaUserPoints: | + | Available events in UserPoints: |
< | < | ||
- | - onBeforeInsertUserActivityBetaUserPoints | + | - onBeforeInsertUserActivityUserPoints |
- | - onAfterUpdateBetaUserPoints | + | - onAfterUpdateUserPoints |
- | - onChangeLevelBetaUserPoints | + | - onChangeLevelUserPoints |
- | - onUnlockMedalBetaUserPoints | + | - onUnlockMedalUserPoints |
- | - onGetNewRankBetaUserPoints | + | - onGetNewRankUserPoints |
- | - onResetGeneralPointsBetaUserPoints | + | - onResetGeneralPointsUserPoints |
- | - onBeforeDeleteUserActivityBetaUserPoints | + | - onBeforeDeleteUserActivityUserPoints |
- | - onAfterDeleteUserActivityBetaUserPoints | + | - onAfterDeleteUserActivityUserPoints |
- | - onBeforeDeleteAllUserActivitiesBetaUserPoints | + | - onBeforeDeleteAllUserActivitiesUserPoints |
- | - onAfterDeleteAllUserActivitiesBetaUserPoints | + | - onAfterDeleteAllUserActivitiesUserPoints |
- | - onBeforeMakeRaffleBetaUserPoints | + | - onBeforeMakeRaffleUserPoints |
- | - onAfterMakeRaffleBetaUserPoints | + | - onAfterMakeRaffleUserPoints |
</ | </ | ||
Line 433: | Line 467: | ||
* Created on 15 January 2016. | * Created on 15 January 2016. | ||
- | * Last updated on 05 April 2023. | + | * Last updated on 25 November 2024. |
userpoints/developer.1683036348.txt.gz · Last modified: 2023/05/02 14:05 by admin