This is a tiny, event-driven interface to the Clopenbadger API that can be used from Webmaker Applications to display earned & available badges for users, as well as credit user behaviors.
All prerequisites are contained in the
Currently this library needs requirejs, jquery, and a special
backbone-events, which simply contains the Backbone.Events
implementation. If your project already uses Backbone, you can use a
much smaller version of the library, or you can create
your own shim that uses your own eventing library as an implementation.
Optionally, this library supports the postmessage-proxied-xhr (PPX) library to allow browsers without CORS support to communicate with a Clopenbadger server on a different origin.
For any details not specified by the following documentation, see
the test suite at
test/all-tests.js for more information.
Create a Clopenbadger instance like this:
var badger = Clopenbadger(options);
options is an object with the following keys:
server- The URL to the server that hosts a Clopenbadger API, e.g.
http://foo.org. It should not have a
/at the end.
token: The JSON Web Token to authenticate with the Clopenbadger server. Construction of this token is explained in the Clopenbadger API documentation.
A Clopenbadger instance emits the following events:
ready- Emitted once the Clopenbadger server has been contacted and initial metadata about available badges and earned badges has been retrieved. Mutually exclusive with the
error- Emitted when an initialization error occurs. Mutually exclusive with the
change:availableBadges- Emitted when metadata about available badges has changed.
change:earnedBadges- Emitted when metadata about the current user's earned badges has changed.
change:unreadBadgeCount- Emitted when the number of new badges a user hasn't seen yet has changed.
award- Emitted when one or more badges have been awarded to the user. The single argument passed is an array of shortnames of the badges that have been awarded.
A Clopenbadger instance has the following methods:
credit(shortname)- Credits the behavior with the given shortname to the user. If a badge is awarded as a result of the credit, an
awardevent is triggered.
markAllBadgesAsRead()- Marks all the user's badges as read (i.e., seen by the user). If the number of unread badges has changed as a result of this call, a
change:unreadBadgeCountevent is triggered.
getBadges()- Returns an array of objects containing combined metadata about badge types and issuance (if any) for the current user.
All of the following properties are read-only.
unreadBadgeCount- The number of unread badges that the user has.
availableBadges- An object mapping badge shortnames to their metadata. Information about issuance is not contained here.
earnedBadges- An object mapping earned badge shortnames to their issuance metadata.
The module at
test/fake-clopenbadger-server.js provides a class that uses
jQuery Ajax Transport middleware to run a fake
Clopenbadger "server" in the embedding webpage and return fake
responses. This is used by Clopenbadger's test suite, but may also be
useful for testing your own code.