Skip to content

Documentation en français

Alain Bolli edited this page · 35 revisions

Table of Contents

Fonctionnalités de la version 1.2

JomBadger est un composant qui permet de gérer des Open Badges.

La version 1.2 est en cours de test et compatible avec Joomla! 3.

La version téléchargeable est encore la version 0.99, compatible seulement avec Joomla 2.5. Elle est maintenant compatible avec la version 1.0 de Open Badges.

Attention, la mise à jour depuis une version précédente de JomBadger n'est pas garantie. Il vaut mieux recommencer par une installation vierge. Si vous avez besoin de conserver les données, il est fortement conseillé de faire une sauvegarde !

Administration

Fonctionnalités dans l'interface d'administration :

  • compatible Open Badges 1.0
  • créer un badge
  • créer une catégorie de badges
  • gérer les éléments créés
  • créer des organisations
  • créer des menus vers des pages pour les visiteurs (voir les fonctionnalités du site public)
  • plugin pour valider automatiquement un badge à la lecture d'un article, sans intervention d'un administrateur
  • plugin pour compter les articles lu et délivrer un badge à partir d'un certain nombre d'articles lus
  • émettre des badges pour une adresse email donnée par le webmaster
  • liste des badges émis
  • éditeur pour modifier les fichiers de langues de l'application
  • API qui permet d'utiliser le système de badge dans d'autres composants (pour développeur)
  • activation d'objectifs. En cas de réussite on obtient un badge.
et vous pouvez gagner votre badge si vous installez le composant et effectuez quelques actions ;-)

Site public

  • affichage de tous les badges que l'on peut obtenir sur le site
  • affichage de la page qui génère le badge, pour les personnes authentifiées
  • envoi du badge dans le backpack
  • validation automatique de badge à l'affichage d'une page
  • affichage des badges gagnés, générés et transférés
  • intégration de facebook
  • une page récapitule les objectifs
  • émission d'un badge à partir du site public pour un utilisateur non authentifié

Fonctionnalités prévues

  • création de plugins pour valider des badges automatiquement dans des situations plus complexe que la simple lecture d'une page
  • possibilité de créer des badges sans les publier tout de suite (comme les articles de Joomla! par exemple)
  • intégration de twitter

Souhaits

  • Vous pouvez ajouter ici des fonctionnalités que vous voudriez avoir dans le composant / plugins.

Mode d'emploi du composant

Principe de fonctionnement

L'utilisateur qui visite votre site effectue différentes actions, dont certaines vont lui valider des badges. Cette partie se fait essentiellement en dehors du composant JomBadger. Par exemple, il complète un quiz et le résultat de ce quiz valide ou non un badge. Le quiz n'est pas dans JomBadger, mais le résultat du quiz est utilisé par le composant. Ensuite l'utilisateur est renvoyé vers une page qui génère le badge, puis lui permet de l'envoyer vers son "sac à badges" (backpack).

Techniquement, seul un point est un peu compliqué, car il nécessite un peu de programmation : une fois les actions qui valident le badge effectuées, il faut l'indiquer à JomBadger. Mais des plugins seront mis à disposition pour automatiser cela dans les cas les plus simples. Nous verrons en détails cet aspect technique plus bas.

Installation du composant

Pas de difficultés ici, le composant s'installe comme tous les composants de Joomla. Il suffit d'importer le fichier zip téléchargé à partir de l'interface d'administration, rubrique "Extensions", "Gestion des extensions", "Installation".

Attention, la mise à jour vers les versions 0.99 et 1.2 n'est pas garantie. Faites des sauvegardes !

Vous devez installer trois éléments :

  • le composant
  • le plugin jbvalidate, pour délivrer un badge à la lecture d'un article (facultatif)
  • le plugin lbarticles, pour compter les articles lus et délivrer un badge pour un certain nombre d'articles lus (facultatif)

Paramètres généraux

Commençons par saisir quelques paramètres. Allez dans l'interface d'administration de Joomla!, puis dans le composant (menu "composants" puis "JomBadger"). Cliquez ensuite sur le bouton "Paramètres" en haut à droite.

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

Les 4 champs de l'onglet "Notification" sont obligatoires, servez vous des infobulles et de l'image ci-dessus pour compléter.

Créer une organisation

L'organisation est la structure qui distribue le badge. Vous devez créer au moins une organisation dans l'onglet "Organisations" de JomBadger avant de créer votre premier badge.

Rassembler des informations

Avant de créer quoi que ce soit, il vous faut rassembler des informations pour vos badges. Il est conseillé de classer les badges dans des catégories. Commencez par vous lister les noms des catégories sur une feuille de papier ;-). Ensuite pour chaque badge, il faudra trouver un nom, une image, une description et définir les critères pour l'obtenir.

Concernant les critères d'obtention, il vous faut créer un article dans Joomla! pour chaque badge que vous créez et noter son url (càd le lien vers la page).

Une fois ces informations rassemblées, vous pouvez commencer.

Créer des catégories

Allez dans le sous-menu "Catégories" du composant et créez vos catégories. Le nom et la description de la catégorie sont utilisés dans la partie publique du site dans la page qui liste tous les badges.

Créer des badges

Les images pour les badges doivent être en ligne. Le plus simple est de les importer à partir du menu "Médias" de Joomla! (menu "Contenus" puis "Gestion des médias"). Créez un dossier "badges" et déposez vos images. Passez la souris au-dessus de l'image pour obtenir son url et notez la.

La création du badge se fait dans le sous-menu "Badges". C'est le sous-menu par défaut. Cliquez sur "Nouveau" et complétez le formulaire. Aidez vous des infobulles pour les informations détaillées. Pour l'image, il vous faut coller l'url de l'image.

Le champ "expire" est la date à laquelle le badge ne sera plus valide. Laissez vide s'il n'y a pas de date limite. Le format de cette date doit être : AAAA-MM-JJ (exemple : 2012-08-18)

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

Emettre un badge

Vous voilà prêt à émettre un badge ! Dans le sous-menu "Emettre un badge", saisissez simplement une adresse mail et un badge. Cela génère deux actions :

  • le badge est validé pour cette adresse mail par un enregistrement dans la base de données
  • un mail est envoyé au propriétaire de l'adresse mail. Ce mail contient un lien pour générer son badge et le transmettre dans son "sac à badge" (backpack de Mozilla).

Créer des menus

Vous pouvez créer différents menus pour le site public :

  • une page qui liste les badges que l'on peut obtenir sur le site
  • une page qui génère les badges (mais mettre cette page dans un menu la rend trop visible)
  • une page avec les badges gagnés
  • une page avec les objectifs

Mon badge

Vous pouvez gagner un badge en utilisant JomBadger ! Suivez simplement les instructions du sous-menus "Mon badge".

Statistiques

Une rubrique donne accès aux badges émis, avec une indication pour savoir s'ils ont été publiés dans le sac à badges.

Editeur de langues

Vous pouvez afficher les fichiers de langues dans un éditeur directement dans l'interface d'administration du composant. Vous pouvez alors modifier le texte pour améliorer la traduction ou pour l'adapter à votre site. Si vous améliorez la traduction, merci d'en faire profiter tout le monde et de l'envoyer à alain.bolli -@- gmail.com :-).

Paramétrer la partie publique du site

C'est ici que le travail est le plus long ;-)

Valider un badge

Vous devez écrire un article qui décrit les critères d'obtention de chaque badge, mais aussi les articles, les activités, les quiz, ... qui permettent d'obtenir ces badges.

Il vous faut donc donner accès à la procédure de validation du badge. Pour le moment il n'y a que trois manières de faire qui ne nécessitent pas de programmation :

  • valider manuellement dans l'interface d'administration.
  • utiliser le plugin jb_validate. Il valide un badge simplement à la lecture d'un article. Voir plus bas pour les détails.
  • utiliser le plugin jb_articles. Il valide un badge une fois qu'on a lu un certain nombre d'articles
Pour les autres cas, il vous faudra passer par de la programmation. Une API est proposée un peu plus bas dans cette page pour vous permettre d'ajouter simplement la fonctionnalité de validation de badge dans d'autres composants.

Générer le badge

Une fois le badge validé, il faut rediriger l'utilisateur vers la page qui génère le badge. On appellera cette page "earnbadge". Pour cela il faut simplement lui donner le lien suivant :

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

où "numéro du badge" est à remplacer par son id. Vous trouverez l'id dans le tableau qui liste les badges.

Vous pouvez aussi ajouter l'adresse mail du gagnant dans l'url ainsi que son nom (facultatif). Dans ce cas le badge pourra être validé sans que l'utilisateur soit connecté sur votre site. Cela donnera :

http://www.votresite.com/index.php?option=com_jombadger&view=earnbadge&badgeid=numero_du_badge&email=toto@bolli.fr&name=alain

Pour faire cette redirection, plusieurs solutions :

  • simplement mettre le lien vers la page "earnbadge" dans un article (mon choix préféré à chaque fois que c'est possible)
  • émettre le badge depuis l'interface d'administration (mail envoyé automatiquement avec ce lien)
  • créer une entrée de menu qui pointe vers cette page.
Pour le dernier cas, cela se fait dans le menu "Menus" de l'interface d'administration de Joomla!. Choisissez le menu dans lequel faire apparaître le lien, puis cliquez sur "Nouveau". Dans "Type de lien de menu", cliquez sur "Sélection" et choisissez "Acquérir un badge" dans la partie "JomBadger". N'oubliez pas de paramétrer le badge à acquérir, sur la droite de la page. Avec cette méthode, vous devez créer une entrée de menu pour chaque badge.

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

Fonctionnement de la page "earnbadge"

Pour accéder à son contenu, l'utilisateur doit être authentifié sur votre site. Il peut ne pas être authentifié si son adresse mail est donnée dans l'url.

La page vérifie dans la base de données si l'adresse email de l'utilisateur authentifié a bien droit au badge dont le numéro est spécifié dans l'url. Si le badge est bien validé, il est alors généré. Le contenu du badge est inscrit dans une table de la base de données. Si le badge n'est pas validé, un message prévient l'utilisateur.

L'utilisateur peut modifier son nom et son adresse mail dans un formulaire.

Enfin, la page "earnbadge" affiche un lien pour transmettre le badge dans le "sac à badges" de Mozilla.

Transmettre le badge

Il ne reste plus qu'à l'utilisateur à transmettre le badge dans son "sac à badges". Cette opération est entièrement gérée dans un popup spécifique à Mozilla. Le badge est transféré sur le site beta.openbadges.org.

Les objectifs

Les objectifs ont fait leur apparition dans la version 1.2.

Lorsqu'un objectif est atteint par l'utilisateur, un badge est délivré. Pour le moment, un seul objectif est disponible : un badge est délivré lorsqu'un nombre défini d'articles sont lus par l'utilisateur. Ce nombre est paramétrable.

Fonctionnement

  • activer le plugin jb_articles
  • dans les paramètres de JomBadger, activer les objectifs qui vous intéressent
  • modifier les paramètres à votre guise (par exemple le nombre d'articles à lire)
  • créer un menu vers la page des objectifs. Ne pas oublier dans les paramètres de ce menu d'indiquer l'id du badge à valider.

Mode d'emploi du plugin jb_validate

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 "earnbadge" indiquera si le badge est validé ou non.

Mode d'emploi du plugin jb_articles

Le plugin jb_articles compte le nombre d'articles lus par un utilisateur donné. Chaque article n'est compté qu'une fois. L'utilisateur doit être authentifié sur le site. Ensuite, Jombadger peut délivrer un badge à partir d'un certain nombres d'articles lus.

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.

Aspects techniques

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

La base de données comporte 5 tables :

  • jb_badges : les badges
  • jb_articles : le nombre d'articles lu pour chaque utilisateur
  • 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, adresse mail)
  • badgeid (integer, id du badge)
C'est à vous de programmer cette action. Voir plus haut dans cette page pour des méthodes sans programmation ou ci-dessous pour une utilisation de l'API qui simplifie le travail.

Intégration dans d'autres composants (API) - développeurs

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

Code de l'API

Voici le code à ajouter dans votre composant :

//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. Pour finir, 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

Exemples d'utilisation

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.

La fonction "validate"

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

Crédits

Licence GPL v2.

JomBadger est développé par 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

Something went wrong with that request. Please try again.