Documentation in English

Alain Bolli edited this page Dec 8, 2013 · 24 revisions

Table of Contents

Features of version 1.2

This page has to be translated. Help is needed, my English is not good enough.

JomBadger is a component for managing Open Badges.

Version 1.2 will soon be available, compatible with Joomla 3. I'm testing it ...

Downloadable version is still 0.99, only compatible with Joomla 2.5. It is now compatible with Open Badges 1.0.

Attention, the update from an older JomBadger's version is not guaranteed. It's better to install from scratch. If you have to maintain datas, it is strongly recommended to make a backup !

Administration

Features in backend :

  • compatible Open Badges 1.0
  • create a badge
  • create categories for your badges
  • manage the created elements
  • create organizations
  • create menus to webpages for your visitors (see frontend features)
  • plugin to automatically validate a badge by reading an article, without intervention from webmaster
  • plugin to count read articles and deliver badge when enough articles read
  • issue badge for a given email by webmaster
  • list of issued badges
  • editor to modify language files
  • API to use badge system in other components (for developers)
  • activating of goals. If goal achieved, you win a badge.
and you can earn your own badge if you install the component and do some actions ;-)

Frontend

  • display a page with all badges you can earn on your website
  • display the page that issues the badge, for authenticated users
  • send badge to your backpack
  • automated badge validation when reading an article
  • display list of earned, generated and transmitted badges
  • Facebook integration
  • page for goals
  • issue badge for non authenticated users

Roadmap

Some coming features :

  • creation of plugins to validate badges automatically in more complex situations than just reading an article
  • possibility to create badges without publish them immediately (like articles in Joomla! for example)
  • integration with twitter

Wishlist

  • you can add here what you would like to see in the component / plugins ...

Howto

Operating principle

The user who visits your site performs different actions, some of which it will validate badges. This part is essentially outside the JomBadger component, which runs the badge functionality only. For example, complete a quiz and the result of this quiz signals the badge validation if programmed to. The quiz is not in JomBadger, but the result of the quiz is used by the component. Then the user is redirected to a page that generates the badge, and then allows him to send it to his Mozilla Backpack. If you are not familiar with the Mozilla Open Badge program, please visit it for more information: http://openbadges.org/

Technically, only one point is a bit complicated because it requires a bit of programming after the actions that validate the badge made​​, it must indicate JomBadger. But plugins are available to automate this in the simplest cases. We will detail the technical aspects lower in the page. Manual validation is possible for those not able to complete the programming aspect, those details are below as well.

Component Installation

No difficulties here, this component installs as other Joomla! components. You just need to import the downloaded zip file from the backend, under "Extensions", "Extensions Manager", "Install".

Attention, update to version 0.99 and 1.2 is not guaranteed. Don't forget to backup !

You have to install three extensions :

  • the component
  • the plugin jb_validate, to deliver badges by reading articles (not mandatory)
  • the plugin jb_articles, to count read articles and deliver badge if enough articles read

Parameters

Begin by entering a few parameters. Go to the administration interface of Joomla, then the component (menu "components" and "JomBadger"). Then click the "Settings" button at the top right.

Image : http://www.bolli.fr/images/doc/parametres.png

The four fields of the tab "Notification" are required, you use tooltips and image above to complete.

Create an organization

The organization is the structure that distributes the badge. You must create at least one organization in the "Organizations" tab before creating your first badge.

Gather badge information

Before creating anything, you need to gather information for your badges. It is advisable to rank badges in categories. Start by listing the category names on a sheet of paper;-). Then for each badge, it will find a name, a picture, a description and define the criteria for it.

Regarding the criteria for obtaining, you must create an article in Joomla! for each badge that you create and record the URL (ie. the link to the page).

Once this information is collected, you can start.

Create categories

Go to the "Categories" submenu of the component and create your categories. The name and description of the class are used in the public part of the website page that lists all the badges.

Create badges

The images for badges must be online. The easiest way is to import from the "Media" menu in Joomla! (found under the "Content" menu then "Media Management"). Create a "pin" folder and drop your images. Hover over the image to get the url and note this for future reference.

The form for the creation of the badge is found in the "Buttons" submenu. This is the sub-menu by default. Click "New" and complete the form. There are tooltips for details on the information requested in case you get confused. For the image, you must paste the URL of the image uploaded in the step above.

The "expires" is the date on which the badge is no longer valid. Leave blank if there is no deadline. The format of the date must be YYYY-MM-DD (eg 2012-08-18)

Exemple : http://www.bolli.fr/images/doc/badge.png

Issue a badge

You're ready to make a badge! In the sub-menu "Issue a badge", simply enter an email address and a badge. This generates two actions:

  • the badge is validated for this mail by a record in the database.
  • an email is sent to the owner of the email address in which he will find a link to create a badge and send to his Mozilla Backpack.

Create menus

You can create different menus for the public site:

  • a page that lists the current badges that can be obtained on the site
  • a page that generates the badges (but this page to a menu makes it too obvious)
  • a page that lists the badges earned
  • a page for the goals

My badge

You can earn a badge using JomBadger! Simply follow the instructions of the sub-menus "My Badge".

Statistiques

A section provides access badges issued with an indication as to whether they were published in the bag tags.

Language editor

You can view the language files in an editor directly in the administration interface of the component. You can then edit the text to improve the translation or to suit your site. If you improve the translation, thank you to share it all and send it to alain.bolli - @ - gmail.com :-).

Set the public site

This is a bit more work ;-)

Validate a badge

You should write an article that describes the criteria for obtaining each card, but also articles, activities, quizzes, ... that achieve these badges.

So you need to give access to the validation procedure for the badge. At the moment there are only three ways to do that do not require programming:

  • You confirm manually in the administration interface.
  • use the plugin jb_validate. It validates a badge just reading an article. See below for details.
  • use the plugin jb_articles. It validates a badge once the user reads enough articles.
In other cases, you will have to develop your component / plugin. An API is provided further down on this page to allow you to simply add badge validation functionality in other components.

Generate the badge

Once the badge is validated, you must redirect the user to the page that generates the badge. We call this page "earnbadge". For this you just need to give the following link:

http://www.YOURSITE.com/index.php?option=com_jombadger&view=earnbadge&badgeid=BADGE_NUMBER

where "BADGE_NUMBER" is replaced by the badge's id number. You can find the id number in the table list of the badges.

You can also add email and name (not mandatory) to the link. In this case, there is no need for the user to be authenticated. So the link is :

http://www.YOURSITE.com/index.php?option=com_jombadger&view=earnbadge&badgeid=BADGE_NUMBER&email=EMAIL&name=NAME

To do this redirection, there are several solutions:

  • just put the link to the page "earnbadge" in an article (my favorite solution whenever possible)
  • issue the badge manually from the administration interface (an email will be sent automatically with this option)
  • create a menu entry that points to the "earnbadge" page.
For the latter case (menu), this is done in the "Menus" menu in the admin interface of Joomla. Choose the menu in which the link to appear, then click "New". In the "Link Type" menu, click "Select" and choose "Earn a badge" in the "JomBadger". Do not forget to set the badge to acquire in the "Configuration" table on the right side of the page. With this method, you must create a menu entry for each badge.

Exemple : http://www.bolli.fr/images/doc/menu.png

How the "earnbadge" page works

To access the content, the user must be registered and logged in on your site. It will work if the user is unregistered if you give his email in the link.

The page checks the database if the email has authenticated the right badge whose number is specified in the user url address. If the badge is validated, it is then generated. The content of the tag is part of a table of the database. If the badge is not valid, a message warns the user.

The user can modify his name and email with a form.

Finally, the page "earnbadge" displays a link to send the badge to the user's Mozilla Backpack.

Transmit the badge

There remains only for the user to transfer the badge to his Mozilla Backpack. This is managed in a specific Mozilla popup. The badge is transferred to the beta.openbadges.org site.

Goals

Goals are available since version 1.2.

When a goal is achieved by the user, a badge is issued. For now, just one goal is available : a badge is issued when enough articles are read by the user. The number of articles can be modified.

How to

  • activate jb_articles plugin
  • In JomBadger parameters, activate goals you are interested in
  • modify parameters (for example the number of articles to read)
  • create a menu to the goal page. Do not forgot to give the badge id to validate in the menu parameters

jb_validate Plugin Howto

Parts of the page have yet to be translated !

Le plugin jb_validate valide l'acquisition d'un badge simplement en lisant une page. L'utilisateur doit être authentifié sur le site et aller sur une page qui contient le plugin. Quand la page est affichée, l'adresse mail de l'utilisateur (celle de son profil) et le numéro du badge sont envoyés dans la base de données de manière totalement transparente.

Pour mettre en place le plugin, il faut bien sur l'installer et l'activer comme n'importe quel plugin. Il n'y a pas de paramètres pour ce plugin.

Ensuite il suffit d'aller dans l'article qui va valider le badge et de rajouter n'importe où dans la page le code suivant :

{jb}numéro du badge{/jb}

Par exemple : {jb}25{/jb} validera le badge numéro 25 pour l'utilisateur authentifié qui lit la page.

Il vous faudra aussi rédiger dans l'article la procédure pour que l'utilisateur puisse vérifier si le badge est validé. En général cela consiste à simplement créer un lien vers la page "earnpage". La page "earnpage" indiquera si le badge est validé ou non.

jb_articles Plugin Howto

The jb_articles plugin counts the articles read by a given user. Each article is counted just once. User has to be authenticated. Then, Jombadger can issue a badge if enough articles are read.

To use the plugin, you have of course to install it and activate it like all joomla plugins. There are no parameters for this plugin.

Technical aspects

JomBadger est composé d'un composant et d'un plugin. Le composant intervient dans l'interface d'administration et dans la partie publique du site.

La base de données comporte 3 tables :

  • jb_badges : les badges
  • jb_articles : number of articles read by a user
  • jb_validated : contient temporairement les infos pour savoir si un badge est validé, à savoir l'adresse mail de l'utilisateur et le numéro du badge
  • jb_records : contient les badges générés par les utilisateurs.
  • jb_issuer : contient les organisations qui délivrent des badges depuis votre site
Les catégories sont enregistrées dans la table des catégories de Joomla!.

Chaque enregistrement de jb_records contient les informations du badge et de l'utilisateur qui le possède. Ces informations sont affichées dans un format JSON lorsque le badge doit être affiché.

Lorsque qu'un utilisateur a effectué les actions nécessaires à la validation d'un badge, il faut inscrire les informations suivantes dans la table #__jb_validated :

  • id_validated (entier auto-incrémenté)
  • usermail (string, email)
  • badgeid (integer, badge id)
C'est à vous de programmer cette action. Voir ci-dessus pour des méthodes sans programmation ou ci-dessous pour une utilisation de l'API qui simplifie le travail.

Integration in other components (API) - developers

Comme vu ci-dessus, la partie la plus délicate est d'automatiser la validation d'un badge. Comment transformer une série d'actions réussies en un badge validé ? Internet regorge de composants qui permettent de faire travailler des compétences. On pense de suite aux quiz, mais aussi simplement à un formulaire comme ChronoForms ou encore au gestionnaire de points AlphaUserPoints. Vous avez trouvé votre composant favoris ? Reste à le modifier pour qu'il communique avec JomBadger.

Certains composants ont mis en place des systèmes de plugins. On peut alors facilement créer de nouvelles fonctionnalités, sans modifier le composant lui-même. D'autres composants nécessitent par contre d'être modifiés directement.

Deux possibilités s'offrent à vous :

  • soit vous codez vous-même l'inscription des données dans la table jb_validated (voir structure plus haut)
  • soit vous utilisez l'API ci-dessous

API Code

Here is the code to add in your component :

//API JomBadger
$api_OBJ = JPATH_SITE'/components/com_jombadger/helper.php';
if ( file_exists($api_OBJ))
	{
  	require_once ($api_OBJ);
   	JomBadgerHelper::validate($earnermail,$badgeid);
	}
//fin API JomBadger

La première ligne indique l'url de la page qui contient le code. La seconde vérifie si cette page existe. Cela permet d'ajouter le code dans un composant tiers sans que cela ne génère d'erreur si JomBadger n'est pas installé.

Ensuite le code est inclus dans le composant tiers. Enfin, une fonction validate est exécutée. Cette fonction a besoin de deux arguments que le composant tiers doit fournir :

  • l'adresse mail de la personne qui a gagné le badge
  • le numéro du badge

Examples

Un exemple d'utilisation :

On veut valider le badge 25 pour l'utilisateur authentifié

$user	= JFactory::getUser();
if ($user)
    {
    $earnermail = $user->email;
    //API JomBadger
    $api_OBJ = JPATH_SITE.'/components/com_jombadger/helper.php';
    if ( file_exists($api_OBJ))
	{
  	require_once ($api_OBJ);
   	JomBadgerHelper::validate($earnermail,25);
	}
    //fin API JomBadger
}

Si le composant doit pouvoir gérer plusieurs numéros de badges, il faut bien sur aussi coder la variable $badgeid.

The "validate" function

La fonction "validate" effectue deux actions :

  • elle vérifie d'abord si l'enregistrement existe déjà (adresse mail + numéro du badge)
  • si l'enregistrement n'existe pas, elle le crée
Elle renvoie une variable qui peut prendre 3 valeurs :
  • 0 en cas de problème si l'enregistrement n'a pas pu se faire
  • 1 si les données ont été enregistrées normalement
  • 2 si les données existaient déjà dans la base de données

Credits

Licence GPL v2.

JomBadger is developped by Alain Bolli (http://www.bolli.fr)

L'inspiration initiale s'est faite à partir du code de badge it gadget Lite développé par gocodery.com