Skip to content
This repository has been archived by the owner on Aug 22, 2019. It is now read-only.

[Docs] - README.md - minor tweaks #1157

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

[Docs] - README.md - minor tweaks #1157

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
250d789
[Docs] - README.md - minor tweaks
Dec 15, 2017
a510b63
fix number two - ortography (minor tweaks)
Dec 15, 2017
939ce25
Table of Contents (ToC)
Dec 15, 2017
cc5e21a
adding thumbnail
Dec 15, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 41 additions & 12 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,24 @@
[![Build Status](https://travis-ci.org/mozilla/openbadges-backpack.png?branch=master)](https://travis-ci.org/mozilla/openbadges-backpack)
[![Dependencies](https://david-dm.org/mozilla/openbadges-backpack.svg)](https://david-dm.org/mozilla/openbadges-backpack)

Table of Contents (ToC)
=======================

* [Welcome to the future of the Backpack](#welcome-to-the-future-of-the-backpack)
* [Call to action!](#call-to-action)
* [What is the Backpack?](#what-is-the-backpack)
* [I want to play with the code, where do I start?](#i-want-to-play-with-the-code-where-do-i-start)
* [Creating a development environment](#creating-a-development-environment)
* [Optional: a real hostname](#optional-a-real-hostname)
* [Database Migrations](#database-migrations)
* [Production](#production)
* [Heroku](#heroku)
* [Open Badges Specifications](#open-badges-specifications)
* [I'm an Issue, How do I use This?](#i-am-an-issuer-how-do-i-use-this)
* [I'm a Displayer, How do I use This?](#i-am-a-displayer-how-do-i-use-this)

---

## Welcome to the future of the Backpack

Backpack-ng (pronounced *'backpacking'*) is the next generation of the Backpack.
Expand All @@ -12,22 +30,26 @@ The [ng branch](https://github.com/mozilla/openbadges-backpack/tree/backpack-ng)

* Updated the framework and most of the dependencies
* Removed Persona as the main authentication mechanism (which is due to be decommissioned on the 31st Nov 2016)
* Replaced Persona with [PassportJS](http://passportjs.org/) (which includes a Persona strategy/plugin to allow users to login with Persona until it is finally decommissioned).
* Replaced Persona with [PassportJS](http://passportjs.org/) (which includes a Persona strategy/plugin to allow users to log in with Persona until it is finally decommissioned).
* Added a new responsive theme

Although we've given the backpack a bit of a facelift, there are still some rough edges to smooth out. The front-end functionality is working as expected (that is, to say, we haven't spotted anything that is majorly broken!). We're currently focusing our attention on the few remaining unit tests that are still failing (these mostly relate to the Backpack API).

---

## Call to action!

If you feel you have something to offer and would like to help develop/design the backpack and push things forward, please feel free to grab the codebase and start hacking. Full setup instructions are below.

We welcome active collaborators, whether you want to discuss contributions to the code base or explore future developments, connect with us at backpack@digitalme.co.uk

---

## What is the Backpack?

The Mozilla Backpack is a placed to store your collections of Open Badges. The Backpack allows earners to import badges and manage them in groups, choosing whether each group is public or not. You can access the Mozilla Backpack Web front-end at: http://backpack.openbadges.org

The Backpack code includes tools for badge issuers and displayers, for pushing awarded badges to an earner's Mozilla Backpack and for retrieving an earner's badges for display. If you're an issuer or displayer, you will find more information on how to start interacting with the Backpack at the bottom of this guide.
The Backpack code includes tools for badge issuers and displayers, for pushing awarded badges to an earner's Mozilla Backpack and for retrieving an earner's badges for display. If you're an issuer or displayed, you will find more information on how to start interacting with the Backpack at the bottom of this guide.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be displayer and not displayed


---

Expand All @@ -44,9 +66,7 @@ The Backpack code includes tools for badge issuers and displayers, for pushing a
GRANT ALL PRIVILEGES ON openbadges_test.* to badgemaker@localhost IDENTIFIED BY 'secret';

2. Copy the `openbadges/lib/environments/local-dist.js` to
`openbadges/lib/environments/local.js` and edit the configuration to match
your local development environment. The MySQL database credentials should
match step #1. For example:
`openbadges/lib/environments/local.js` and edit the configuration to match your local development environment. The MySQL database credentials should match step #1. For example:

database: {
driver: 'mysql',
Expand Down Expand Up @@ -87,7 +107,7 @@ migration. You can do this as follows:
`add-issuer-column`.

2. Run `./bin/db-migrate create add-issuer-column`. This will create a new JS
file preixed with a timestamp in the `migrations` directory.
file prefixed with a timestamp in the `migrations` directory.
Something like the following should be displayed:

[INFO] Created migration at
Expand All @@ -111,7 +131,7 @@ If you want to write tests for your migration, check out

### Production

The codebase behaves slightly differently when run in an environment where
The codebase behaves slightly differently when running in an environment where
environment variable `NODE_ENV=production`. These differences include:

* less verbose logging
Expand All @@ -123,9 +143,9 @@ environment variable `NODE_ENV=production`. These differences include:

Heroku relies upon the [habitat](https://github.com/brianloveswords/habitat) environment variables loader library. The config for this can be found in [lib/environments/heroku.js](lib/environments/heroku.js).

When configuring your environment variables on heroku, they should be prefixed with the string that is passed to the habitat constructor. For example, if we pass the string "openbadges" to our habitat constructor, like so: `new Habitat("openbadges")`, then in heroku our protocol env var would be "OPENBADGES_PROTOCOL" (with, in this case, a value set to either http or https).
When configuring your environment variables on Heroku, they should be prefixed with the string that is passed to the habitat constructor. For example, if we pass the string "open badges" to our habitat constructor, like so: `new Habitat("open badges")`, then in Heroku our protocol env var would be "OPENBADGES_PROTOCOL" (with, in this case, a value set to either HTTP or https).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The string openbadges is acceptable and correct.

Also, if we uppercase HTTP we should probably uppercase HTTPS too.


Currently, the heroku env var config looks like so...
Currently, the Heroku env var config looks like so...


| ENV VAR | VALUE EXAMPLE |
Expand Down Expand Up @@ -164,24 +184,33 @@ To work with the Mozilla Backpack as either an issuer or a displayer, you will b

For more information about Open Badges, check out http://openbadges.org

---

## I'm an Issuer, how do I use this?

The Backpack includes the following tools for badge issuers:

* [Issuer API](docs/apis/issuer_api.md)
* For pushing badges you have awarded the earner to their Mozilla Backpack, giving the earner the ability to approve the push through a lightboxed modal. The API is written in Javascript, and is includable in your project with just a few lines of JS.
* For pushing badges you have awarded the earner to their Mozilla Backpack, giving the learner the ability to approve the push through a lightbox modal. The API is written in Javascript, and is includable in your project with just a few lines of JS.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Earner is the correct term.

Copy link

@ottonomy ottonomy May 23, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"recipient"? https://openbadgespec.org/#recipient

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ottonomy Yeah, that is even better! ;)

* [Backpack Connect API](docs/apis/backpack_connect.md)
* For pushing to the earner's Mozilla Backpack via persistent access, with permission granted by the earner.
* [Baker API](docs/apis/baking_api.md)
* For embedding badge metadata into the badge image (_not required if you use the Issuer API_).

Requirements:

* Webserver capable of serving requests to the general internet.
* Web server capable of serving requests to the general internet.
* Ability to make a POST request from your server backend and read a JSON response.
* Email addresses of the users you wish to issue badges.
* Badge image must be in PNG format.

---

## I'm a Displayer, how do I use this?

The Backpack includes the [Displayer API](docs/apis/displayer_api.md), via which badge displayers can retrieve earner badges from their Mozilla Backpack. You will only be able to retrieve badges that the earner has chosen to make public. Given the earner email address, you can first use the conversion service to retrieve the earner's Backpack ID, then use that ID to query for public badge groups. Each group contains a list of badges awarded to the earner, inclding the information you need to present the badges within your site, application or other display implementation.
The Backpack includes the [Displayer API](docs/apis/displayer_api.md), via which badge displayers can retrieve earner badges from their Mozilla Backpack. You will only be able to retrieve badges that the learner has chosen to make public. Given the earner email address, you can first use the conversion service to retrieve the earner's Backpack ID, then use that ID to query for public badge groups. Each group contains a list of badges awarded to the earner, including the information you need to present the badges within your site, application or other display implementation.

---

<img src="https://avatars2.githubusercontent.com/u/131524?s=200&v=4" width="100"></img>
<img src="http://cdn.ttgtmedia.com/ITKE/cwblogs/open-source-insider/Mozilla%20PL.png" width="225"></img>