[[PageOutline]]
= Badges =

'''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 [HtmlOps 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 default badges ==

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.

[[Image(http://boinc.berkeley.edu/badges/pct_1.png)]]
[[Image(http://boinc.berkeley.edu/badges/pct_5.png)]]
[[Image(http://boinc.berkeley.edu/badges/pct_25.png)]]

The script that assigns these badges is here:
http://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>
}}}

== Writing a badge-assignment script ==

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).

== Another example badge-assignment script ==

If your project tracks [PerAppCredit 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'''.

== Badge display ==

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:
 BADGE_HEIGHT_SMALL:: Forums.
 BADGE_HEIGHT_MEDIUM:: Tabular lists (e.g. top user list).
 BADGE_HEIGHT_LARGE:: 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.