Overview
One of the most frequently requested customizations by AnswerHub administrators is a new badge or series of badges to award to their site users. Out of the box, AnswerHub provides a broad variety of badges that encourage desired user behavior or reward users for active site participation. It also provides a framework that makes it simple to add new badges.
Information
Your new badge or badges can be placed into their own plugin or added to a plugin that you already have.
In this article, we are going to show you how to create a Participant badge, that will be awarded to users who fill out their profile details, ask at least one question, and answers at least one question.
The following components are involved in creating a new badge:
- Specifying the details of the badge and all of its requirements
- Adding the badge to the list of AnswerHub available badges
- Specifying i18n keys and definitions
- Adding an icon to the badge
Throughout this article, the words badge and award are used pretty much interchangeably, as some customers prefer to call them badges, and others like awards better.
Creating a badge
The foundation for all awards is the BuiltinAwardRunner interface which specifies all the criteria for an award. The following code demonstrates creating the new Participant badge using the BuiltinAwardRunner interface. All methods specified below are required and must be implemented by your award.
package com.teamhub.plugins.tutorial.awards;
import java.util.*;
import com.teamhub.infrastructure.spring.RequestInfo;
import com.teamhub.managers.award.builtin.BuiltinAwardRunner;
import com.teamhub.managers.generic.DirectQueryManager;
import com.teamhub.managers.node.NodeManager;
import com.teamhub.models.action.Action;
import com.teamhub.models.action.AnswerAction;
import com.teamhub.models.action.AskAction;
import com.teamhub.models.action.UserEditAction;
import com.teamhub.models.award.Award;
import com.teamhub.models.award.AwardType;
import com.teamhub.models.node.Answer;
import com.teamhub.models.node.Question;
import com.teamhub.models.site.Site;
import com.teamhub.models.user.User;
import org.springframework.beans.factory.annotation.Autowired;
public class Participant implements BuiltinAwardRunner {
@Autowired
NodeManager nodeManager;
@Autowired
DirectQueryManager queryManager;
@Override
public String getName() {
return ""awards.participant.name"";
}
@Override
public String getDescription() {
return ""awards.participant.description"";
}
@Override
public AwardType.Level getLevel() {
return AwardType.Level.bronze;
}
@Override
public AwardType.Mode getMode() {
return AwardType.Mode.per_user;
}
@Override
public Set<Class<?>> getListening() {
Set<Class<?>> listening = new HashSet<Class<?>>();
listening.add(UserEditAction.class);
listening.add(AskAction.class);
listening.add(AnswerAction.class);
return listening;
}
@Override
public boolean canAward(RequestInfo info, Action action) {
User user = action.getUser();
Boolean canAward = user != null &&
user.getRealname() != null && !user.getRealname().isEmpty() &&
user.getDescription() != null && !user.getDescription().isEmpty() &&
user.getLocation() != null && !user.getLocation().isEmpty() &&
user.getBirthday() != null;
canAward = canAward &&
nodeManager.getQueryPlanner(Question.class)
.withAuthor(user)
.applyAclProtection()
.getCount() > 0 &&
nodeManager.getQueryPlanner(Answer.class)
.withAuthor(user)
.applyAclProtection()
.getCount() > 0;
return canAward;
}
@Override
public Collection<Award> award(RequestInfo info, Action action) {
Award award = new Award();
award.setUser(action.getUser());
return Collections.singletonList(award);
}
@Override
public Collection<Award> catchUp(Site site, String key,
final AwardType awardType) {
List<User> userList = queryManager.runSelect(
""select distinct u from ""
+ User.class.getSimpleName() + "" u""
+ "" join u.nodes q""
+ "" join u.nodes a""
+ "" where q.class="" + Question.class.getSimpleName()
+ "" and a.class="" + Answer.class.getSimpleName()
+ "" and u.id = q.author and u.id=a.author""
+ "" and u.realname is not null""
+ "" and u.description is not null""
+ "" and u.location is not null""
+ "" and u.birthday is not null""
+ "" and not exists (from Award w where w.type = :type ""
+ "" and w.user=u.id)"",
Collections.<String, Object>singletonMap(""type"", awardType));
List<Award> awards = new ArrayList<Award>();
for (User u : userList) {
Award award = new Award();
award.setUser(u);
awards.add(award);
}
return awards;
}
}
As you can see, we customize the BuiltinAwardRunner to define values specific to our Participant badge.
- We override the getName() and getDescription() methods to specify the keys to the name and description of the badge. These can be any string, but by convention, we specify the prefix “awards.”, followed by the award name, followed by the suffix “.name” for name, and “.description” for description. If the badge is one of a set of badges of different levels, it is also customary to specify the level of the badge after the badge name. So, the Participant badge name can also be “awards.Participant.bronze.name”.
- We override the getLevel() method to specify the level of the badge. AnswerHub supports three badge levels: AwardType.Level.bronze, AwardType.Level.silver, and AwardType.Level.bronze.
- We override the getMode()method to specify how this badge is awarded. AnswerHub supports the following mode types:
AwardType.Mode.per_user – the badge is awarded once per user. The Participant badge is only awarded once per user since the set of Actions that earn this badge occur only once per user.
AwardType.Mode.per_user_and_site – the badge is awarded once per user on a site. For single-site implementations, this is the same as AwardType.Mode.per_user badges.
AwardType.Mode.per_node – the badge is awarded once per node. A node is any type of post: question, answer, comment, idea, etc. This badge is given to a user performing an Action or set of Actions on a node. For example, a badge can be given to the first user that answered a question that had remained unanswered for 30 days.
AwardType.Mode.per_user_and_node – the badge is awarded once per user and node. This badge is given to the author of a node for a set of Actions that occur on that node. For example, a badge can be given to the author of an accepted answer that was voted up 500 times.
AwardType.Mode.per_author_and_node – the badge is awarded once per author and node. This badge is given to the author of the node for a set of Actions performed on their own node. For example, a badge can be given to an author for deleting their own post after it was voted down 10 times.
AwardType.Mode.any – this badge can be awarded any number of times per user and is not tied to any particular node.
For example, a badge can be given to a user for each additional user they invite to join the site.
- We override the getListening() method to specify a set of classes for the actions that may trigger out the badge. Since the Participant badge requires editing the user’s profile, asking one question, and answering one question, we specify the classes for the three actions corresponding to these requirements: UserEditAction.class, AskAction.class, and AnswerAction.class.
- We override the canAward()method to determine if all the required events have been met for the badge to be awarded. The canAward() method is called every time one of the events we are listening for occurs. In the canAward() method of the Participant award, we first check to see if the user performing the action has the required profile fields filled out. We then use the nodeManager to check and see if this user has asked at least one question and has answered at least one question. If all of these conditions have been met, the canAward() method returns true, otherwise, it returns false.
- We override the award() method to create the badge. Once the canAward() method returns true, the award() method is called to award the actual badge and also perform any additional actions that may be required upon awarding the badge.
- Finally, we override the catchUp() function. When our plugin is deployed, there may already be users that are eligible to receive the Participant badge. The catchUp() method allows us to find these users and award the Participant badge to all of them at once. The first thing we do is use the queryManager to query the database for all the users that are eligible for our badge, that is, all users that have their profile fields filled out, and have at least one question node and one answer node. We also want to exclude any users that already have the Participant badge. Once we have our list of users, we create an award for each user and return a list of all the awards.
We have now specified everything we need to award the Participant badge to users that fulfill the badge requirements.
Letting AnswerHub know about the new badge
Once we create the badge bean, we need to add it to the XML plugin configuration file, so it is inserted into the list of badges known to AnswerHub. We add the following line to the XML plugin configuration file:
<award key=""tutorial-participant-award"" class=""com.teamhub.plugins.tutorial.awards.Participant""/>
Specifying i18n keys and definitions
Remember the keys that we specified above in the getName() and getDescription() methods? We will now use these keys to define the name and the description that users will see when our new badge is displayed in AnswerHub. We add the two keys to the tutorial.properties file, in the /src/main/resources directory of our hypothetical tutorial plugin. Each plugin can have its own i18n properties file to specify words and phrases specific to that plugin. See the "Overview of AnswerHub i18n" (TODO LINK HERE) article for more information on AnswerHub keys and localization.
awards.participant.name=Participant awards.participant.description=Completed profile fields, asked a question and answered a question
Adding a badge icon
The last thing we need to do is to add an icon to our badge to give it some unique style. Create a PNG icon of the same size as other badge icons in AnswerHub. You will need to use the getName() key specified above as the name of your icon. So, the Participant badge icon will be named awards.participant.name.png. Place the icon into the /src/main/resources/theme-resource/base/images/badges directory of your plugin in order for AnswerHub to find it.
Now you have all the components necessary to create a simple badge in AnswerHub. You can use these to create custom badges for your site, simply change the name or description of an existing badge or add a new icon to a badge.
Priyanka Bhotika
Comments