BadgeDoc
Badges are symbols of accomplishment by volunteers or teams - for example, how much computing they've contributed. Badges are shown as icons on project web sites. In the future, they may also be shown in client GUIs and statistics sites.
BOINC provides a general mechanism for defining and assigning badges. You can create badges for whatever accomplishments you want - average credit, total credit, length of participation, number of message-board posts, etc.
The data associated with a badge includes:
- A name (used to identify the badge internally; not visible to users)
- The URL of an image file. Images are sized on display (currently 48 pixels high). Make them somewhat larger than this, e.g. 300x300 pixels. For flexibility, use a PNG with transparent background.
- A title - a phrase that explains the accomplishment for which the badge is granted.
The administrate web interface has a page for administering badges, which lets you add and remove badges.
Badges are typically granted (or removed) by a PHP script that you run as a periodic task from your config.xml file.
The BOINC server code supports badges for the top 1%, 5%, and 25% of recent average credit (RAC). They are represented by gold, silver, and bronze medal images, respectively, and are assigned to both users and teams.
The script that assigns these badges is here: https://boinc.berkeley.edu/gitweb/?p=boinc-v2.git;a=blob;f=html/ops/badge_assign.php
To enable these badges on your project's site, add the following to your config.xml file:
<task>
<cmd>run_in_ops ./badge_assign.php</cmd>
<period>24 hours</period>
<output>badge_assign.out</output>
</task>You can use the default badge-assignment script as a template for writing your own. The script uses the following utility functions, defined in html/inc/util_ops.inc:
get_badge($name, $title, $image_url)Return a PHP object representing the badge with the given name, title, and image file URL. Badge descriptions are stored in the MySQL database; this function creates a DB record if it's not already there.
assign_badge($is_user, $item, $badge)Assign the given badge to the given user or team; item is either a user or a team Object which has an id property. Usually this is one of the items returned by BoincUser::enum_fields() or BoincTeam::enum_fields().
unassign_badges($is_user, $item, $badges, $k)Remove badges from a given user or team. $badges is a vector of badges to remove. Remove all except the $kth one; if $k is negative, remove them all.
Using these utility functions, the example script works as follows:
- Use get_badge() to get the gold, silver, and bronze badge objects.
- get_percentiles(): compute the top 1, 5, and 25 percentile values of RAC.
- assign_badges(): loop over the set of all items (users or teams). This is done 1000 items at a time to limit memory usage.
- For each item, compare its RAC with the RAC percentiles, and determine which badge to assign (if any). Assign that badge, and unassign the others.
These steps are performed first for users, then for teams.
While you're developing your own badge assignment script, you can run it manually in your project's html/ops directory. Use the admin web interface to clean up badge records as needed. When you're done, arrange to run the script periodically by adding it as a task in config.xml (see above).
If your project tracks per-app credit, you can assign badges based on per-app total credit. A script for doing that is in html/ops/badge_assign_custom.php.
You can control the display of badges on your project's web site by defining the following constants in your html/project/project.inc:
define('BADGE_HEIGHT_SMALL', 20);
define('BADGE_HEIGHT_MEDIUM', 24);
define('BADGE_HEIGHT_LARGE', 56);These define the height of badge images in different contexts:
Forums.
Tabular lists (e.g. top user list).
User and team pages.
If you set any of these to zero, badges will not be shown in that context. The default values are those given above.