Difference between revisions of "Award points to users using CjForum Points System"

From CjWiki
Jump to navigation Jump to search
Line 2: Line 2:
 
== Prerequisites: ==
 
== Prerequisites: ==
 
Add the required CjForum API library:
 
Add the required CjForum API library:
<syntaxhighlight lang="php">require_once JPATH_ROOT.'/components/com_cjforum/lib/api.php';</syntaxhighlight>
+
<pre>require_once JPATH_ROOT.'/components/com_cjforum/lib/api.php';</pre>
  
 
Now get the Points API:
 
Now get the Points API:
<syntaxhighlight lang="php">$pointsApi = CjForumApi::getPointsApi();</syntaxhighlight>
+
<pre>$pointsApi = CjForumApi::getPointsApi();</pre>
  
 
== Creating rules XML file ==
 
== Creating rules XML file ==
 
A rules xml file needs to be created with all rules which you would like to provide with your component. An example of the rules xml file is:
 
A rules xml file needs to be created with all rules which you would like to provide with your component. An example of the rules xml file is:
  
<syntaxhighlight lang="xml">
+
<pre>
 
<?xml version="1.0" encoding="UTF-8"?>
 
<?xml version="1.0" encoding="UTF-8"?>
 
<cjforum>
 
<cjforum>
Line 24: Line 24:
 
</points_rule>
 
</points_rule>
 
</cjforum>
 
</cjforum>
</syntaxhighlight>
+
</pre>
  
 
Save this file as '''administrator/components/com_mycomponentname/cjforum_rules.xml'''. You can package the xml file with your component so that it will be automatically installed along with your component. After installing the file, users can scan for rules and the rules will automatically gets installed. You may want to add as many points_rule elements as you need for your component.
 
Save this file as '''administrator/components/com_mycomponentname/cjforum_rules.xml'''. You can package the xml file with your component so that it will be automatically installed along with your component. After installing the file, users can scan for rules and the rules will automatically gets installed. You may want to add as many points_rule elements as you need for your component.
Line 57: Line 57:
  
 
Award points to the logged in user when a user submitted an article (example rule id com_content.create_article)
 
Award points to the logged in user when a user submitted an article (example rule id com_content.create_article)
<syntaxhighlight lang="php">$pointsApi->awardPoints('com_content.create_article');</syntaxhighlight>
+
<pre>$pointsApi->awardPoints('com_content.create_article');</pre>
  
 
Award points to the logged in user when a user submitted an article (example rule id com_content.read_article) and restrict awarding points one time for this article.
 
Award points to the logged in user when a user submitted an article (example rule id com_content.read_article) and restrict awarding points one time for this article.
<syntaxhighlight lang="php">$pointsApi->awardPoints('com_content.read_article', 0, 0, $articleId);</syntaxhighlight>
+
<pre>$pointsApi->awardPoints('com_content.read_article', 0, 0, $articleId);</pre>
  
 
Award 10 points to user when user with id 92 do some task on your component (example rule name: com_mycomponent.my_rule_name):
 
Award 10 points to user when user with id 92 do some task on your component (example rule name: com_mycomponent.my_rule_name):
<syntaxhighlight lang="php">$pointsApi->awardPoints('com_mycomponent.my_rule_name', 92, 10);</syntaxhighlight>
+
<pre>$pointsApi->awardPoints('com_mycomponent.my_rule_name', 92, 10);</pre>

Revision as of 03:58, 8 August 2019

Prerequisites:

Add the required CjForum API library:

require_once JPATH_ROOT.'/components/com_cjforum/lib/api.php';

Now get the Points API:

$pointsApi = CjForumApi::getPointsApi();

Creating rules XML file

A rules xml file needs to be created with all rules which you would like to provide with your component. An example of the rules xml file is:

<?xml version="1.0" encoding="UTF-8"?>
<cjforum>
	<points_rule>
		<name>com_cjforum.new_topic</name>
		<appname>com_cjforum</appname>
		<title>New topic</title>
		<description>Points awarded for posting a topic.</description>
		<points>1</points>
		<state>1</state>
		<auto_approve>1</auto_approve>
		<access>1</access>
	</points_rule>
</cjforum>

Save this file as administrator/components/com_mycomponentname/cjforum_rules.xml. You can package the xml file with your component so that it will be automatically installed along with your component. After installing the file, users can scan for rules and the rules will automatically gets installed. You may want to add as many points_rule elements as you need for your component.

Explanation

<name> - A unique name to your rule
<appname> - extension name, e.g. com_cjforum
<title> - title shown for points detail
<description> - brief description of the points rule
<points> - default amount of points awarded in case site administrator do not configure this
<auto_approve> - if set to 1, points will be published automatically without administrator approval
<access> - access level of this rule, awarded to users only if his access level satisfies. 1 for public user.

Syntax: awardPoints

Full Syntax of the awardPoints API call:

awardPoints($ruleId, $userId = 0, $points = 0, $reference = null, $title = null, $description = null)
$ruleId - string
name of the rule for which you are triggering the points rule.
$userId - int
id of the user to whom points will be awarded. If not provided or provided 0 as value, logged in user id will be taken. Optional parameter.
$points - int
amount of points need to be awarded. If not provided or provided 0 as value, points set by the administrator in rule configuration will be taken. Optional parameter.
$reference - any
primary key value used for restricting multiple points awarded for the same asset. For example, to restrict awarding multiple points when an article is read, give article id as reference number.
$title - string
title to be shown about this award. If not given/null, the title from the rule configuration will be taken. Optional parameter.
$description - string
description to be shown about this award. If not given/null, the description from the rule configuration will be taken. Optional parameter.

Examples:

Award points to the logged in user when a user submitted an article (example rule id com_content.create_article)

$pointsApi->awardPoints('com_content.create_article');

Award points to the logged in user when a user submitted an article (example rule id com_content.read_article) and restrict awarding points one time for this article.

$pointsApi->awardPoints('com_content.read_article', 0, 0, $articleId);

Award 10 points to user when user with id 92 do some task on your component (example rule name: com_mycomponent.my_rule_name):

$pointsApi->awardPoints('com_mycomponent.my_rule_name', 92, 10);