Documentation by Black Sheep Research

User Tools

Site Tools

Trace:
betauserpoints:developer

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
betauserpoints:developer [2023/04/07 09:15] – adminbetauserpoints:developer [2023/04/07 09:32] (current) – admin
Line 1: Line 1:
-BetaUserPoints Developers API documentation +====== BetaUserPoints API documentation ====== 
-===========================================+
  
 Introduction BetaUserPoints - API integration in a Third party component (advanced) Introduction BetaUserPoints - API integration in a Third party component (advanced)
Line 7: Line 7:
 Licence: BetaUserPoints is released under license GNU/GPL License. Author: Bernard Gilly – Adrien Roussel - Martin Brampton. This project started as AlphaUserPoints back in 2008. Licence: BetaUserPoints is released under license GNU/GPL License. Author: Bernard Gilly – Adrien Roussel - Martin Brampton. This project started as AlphaUserPoints back in 2008.
  
-Plugin/Rule creation +===== Plugin/Rule creation =====
---------------------+
  
 A plugin creation (new rule creation for a 3rd party component) is done in 2 steps A plugin creation (new rule creation for a 3rd party component) is done in 2 steps
  
  
-### Step1 - API insertion in a component+=== Step1 - API insertion in a component ===
  
 Just insert the following API in the component code where needed. The best way 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. Just insert the following API in the component code where needed. The best way 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+=== Basic API ===
  
    
Line 41: Line 40:
  
  
-### Attribute points to another user than the current user+=== 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 BetaUserPoints (BUPID) 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. To give points to anothe user than the one connected, only the user id is required. To get his BetaUserPoints (BUPID) 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.
Line 55: Line 54:
 </code> </code>
  
-### 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 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.
Line 64: Line 63:
     {     {
         require_once $api_BUP;           require_once $api_BUP;  
-        $keyreference = BetaUserPointsHelper::buildKeyreference('function_name', ‘item id’ );  +        $keyreference = BetaUserPointsHelper::buildKeyreference('function_name', 'item id' );  
         BetaUserPointsHelper::newpoints( 'function_name', '', $keyreference);           BetaUserPointsHelper::newpoints( 'function_name', '', $keyreference);  
     }     }
 </code> </code>
  
-### Adding information datas+=== Adding information datas ===
  
 To add information datas to be displayed in the action details, just add a new parameter as follows: To add information datas to be displayed in the action details, just add a new parameter as follows:
Line 78: Line 77:
     {     {
         require_once $api_BUP;           require_once $api_BUP;  
-        $keyreference = BetaUserPointsHelper::buildKeyreference('function_name', ‘item id’ );  +        $keyreference = BetaUserPointsHelper::buildKeyreference('function_name', 'item id' );  
         BetaUserPointsHelper::newpoints( function_name','', $keyreference,'information_datas');           BetaUserPointsHelper::newpoints( function_name','', $keyreference,'information_datas');  
     }     }
 </code> </code>
  
-### 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'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.
Line 92: Line 91:
     {     {
         require_once $api_BUP;           require_once $api_BUP;  
-        $keyreference = BetaUserPointsHelper::buildKeyreference('function_name', ‘item id’ );  +        $keyreference = BetaUserPointsHelper::buildKeyreference('function_name', 'item id' );  
         BetaUserPointsHelper::newpoints( function_name','', $keyreference,'',-1450);           BetaUserPointsHelper::newpoints( function_name','', $keyreference,'',-1450);  
     }     }
 </code> </code>
  
-### Get the result from a successful operation+=== Get the result from a successful operation ===
  
 In a more advanced code, if the component routine needs to know if the operation has been successful 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: In a more advanced code, if the component routine needs to know if the operation has been successful 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:
Line 114: Line 113:
 </code> </code>
  
-### Remove the constraint on the type of user+=== 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_. 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+=== 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 you can display a specific message on frontend by adding the parameter frontmessage=”You custom message”. API full implementation
Line 137: Line 136:
 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 BetaUserPoints, in backend administrator to allows your users to have a negative account. 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 BetaUserPoints, in backend administrator to allows your users to have a negative account.
  
-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 (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: [betauserpoints_rule.xml](images/stories/documentation/betauserpoints/betauserpoints_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”. 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 (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: [betauserpoints_rule.xml](images/stories/documentation/betauserpoints/betauserpoints_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”.
Line 144: Line 142:
 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: betauserpoints_rule.xml 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: betauserpoints_rule.xml
  
-### Code list for categories :+=== Code list for categories : ===
  
 <code> <code>
Line 167: Line 165:
 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). 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 +==== Plugin/Rule installation ====
-------------------------+
  
 - auto-detect xml file at the root of frontend component: - 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. 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 informations in a third party component +==== Using BetaUserPoints information in a third party component ====
-------------------------------------------------------------+
  
 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 183: Line 179:
 </code> </code>
  
-### Profil informations+=== Profile information ===
  
 To get the entire profil information, just use the function getUserInfo(); To get the entire profil information, just use the function getUserInfo();
Line 243: Line 239:
 </code> </code>
  
-### Get BUP avatar of user+=== Get BUP avatar of user ===
  
 Display the image of avatar from BetaUserPoints. Display the image of avatar from BetaUserPoints.
Line 254: Line 250:
  
  
-### Get link to BUP user profil+=== Get link to BUP user profile ===
  
 Get the url to show the profil of user. Get the url to show the profil of user.
Line 262: Line 258:
 </code> </code>
  
-### Get link to BUP users list+=== Get link to BUP users list ===
  
 Get the url to show the list of users with points etc… Get the url to show the list of users with points etc…
Line 271: Line 267:
  
  
-### Get avatar Path of a user+=== Get avatar Path of a user ===
  
 Get the path avatar path of a specific user Get the path avatar path of a specific user
Line 280: Line 276:
  
  
-### Get avatar Live Path of a user+=== Get avatar Live Path of a user ===
  
 Get the live url avatar path of a specific user Get the live url avatar path of a specific user
Line 288: Line 284:
 </code> </code>
  
-### Get the medals list of a user+=== Get the medals list of a user ===
  
 <code php> <code php>
Line 311: Line 307:
     if(!defined("_BUP_MEDALS_PATH"))     if(!defined("_BUP_MEDALS_PATH"))
     {     {
-        define('_BUP_MEDALS_PATH', JURI::root() . 'components/com_betauserpoints/assets/images/awards/large/’);+        define('_BUP_MEDALS_PATH', JURI::root() . 'components/com_betauserpoints/assets/images/awards/large/');
     }     }
     if(!defined("_BUP_MEDALS_LIVE_PATH"))     if(!defined("_BUP_MEDALS_LIVE_PATH"))
Line 324: Line 320:
 </code> </code>
  
-### Get the ReferreID of any user+=== Get the ReferreID of any user ===
  
 <code php> <code php>
Line 333: Line 329:
  
  
-### Get the current total points of any user+=== Get the current total points of any user ===
  
 Use the first method with the referreid to get the total of points Use the first method with the referreid to get the total of points
Line 347: Line 343:
 </code> </code>
  
-### Get the list of activities+=== Get the list of activities ===
  
 <code php> <code php>
Line 383: Line 379:
 </code> </code>
  
-### Get the next user rank+=== Get the next user rank ===
  
 <code php> <code php>
-$nextrankinfo = BetaUserPointsHelper::getNextUserRank($referrerid='’, $userid='0', currentrank);+$nextrankinfo = BetaUserPointsHelper::getNextUserRank($referrerid='', $userid='0', currentrank);
 </code> </code>
  
Line 399: Line 395:
 </code> </code>
  
-### Get version of BUP+=== Get version of BUP ===
  
 <code php> <code php>
Line 405: Line 401:
 </code> </code>
  
-Returns the current version of BetaUserPoints like -> 1.0.0+Returns the current version of BetaUserPoints like -> 4.0.0
  
  
  
-BetaUserPoints is open for third component +==== BetaUserPoints is open for third component ====
-------------------------------------------+
  
 Create your own plugin for BetaUserPoints ! Create your own plugin for BetaUserPoints !
Line 437: Line 432:
  
 * Created on 15 January 2016. * Created on 15 January 2016.
 +
 * Last updated on 05 April 2023. * Last updated on 05 April 2023.
  
betauserpoints/developer.1680858954.txt.gz · Last modified: 2023/04/07 09:15 by admin