A Blockcerts verifier and viewer
Branch: master
Clone or download
Latest commit f4f6a85 Feb 21, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
demo chore(Docs): [#762] document theme API Feb 14, 2019
docs/ADR chore(Package): rename package name Sep 11, 2018
sanitizer style(Lint): lint Jan 29, 2019
src
test test(Footer): [#762] fix verify other certificate test Feb 14, 2019
.babelrc chore(BuildProcess): re-added babelrc file for wct tests Aug 24, 2018
.gitignore chore(Codecov): added coverage folder to gitignore Feb 4, 2019
.npmignore chore(NPM): configure for publish Sep 7, 2018
.npmrc chore(NPM): bump version Sep 7, 2018
.nvmrc chore(Setup): fix node version to latest 9 May 23, 2018
.sass-lint.yml refactor(Styles): use sass variable Jul 2, 2018
.travis.yml chore(Codecov): added codecov commands in travis yml Feb 4, 2019
LICENSE.md chore(License): add license Sep 11, 2018
README.md
index.html chore(Package): rename package name Sep 11, 2018
package-lock.json chore(CVJS): update to lastest version Feb 14, 2019
package.json chore(Lint): add precommit lint Feb 14, 2019
polymer.json chore(polymer): polymer init May 13, 2018
rollup-sanitizer.config.js chore(BuildProcess): renamed build sanitizer Aug 23, 2018
rollup.config.js style(Lint): lint Sep 14, 2018
wct.conf.json chore(Setup): run browsers in headless mode on CI May 23, 2018

README.md

<blockcerts-verifier>

Build Status codecov semantic-release

A standalone universal viewer & verifier for blockcerts credentials

Production

The component is developed with Polymer 3. To use the component in your project, install it via:

  npm i @blockcerts/blockcerts-verifier

If your project does not require support for IE11, you can use the following build:

  <script src="node_modules/@blockcerts/blockcerts-verifier/dist/main.js"></script>

  <blockcerts-verifier></blockcerts-verifier>

Chrome will support natively the code, but for Firefox, Safari, MS Edge (Opera and Brave), you will need to add the webcomponent loader before:

    <script src="node_modules/@webcomponents/webcomponentsjs/webcomponents-loader.js"></script>

If your project requires support for IE11, you will need to use the ie11 build:

  <script src="node_modules/@webcomponents/webcomponentsjs/custom-elements-es5-adapter.js"></script>
  <script src="node_modules/@webcomponents/webcomponentsjs/webcomponents-loader.js"></script>
  <script src="node_modules/@blockcerts/blockcerts-verifier/dist/ie11.js"></script>

Please note that because this is transpiled to ES5, the custom-elements-es5-adapter code is required for it to work properly in more modern browsers.

Have a look at the Demo Pages to see examples of the usage

API Usage

Default behavior

By the default, the component will:

  • Display a Blockcerts record in card mode (concise information)
  • Will allow verification of a Blockcerts Record
  • Enables auto-verification (verification as the record is loaded)

API

The component will understand the following options:

  • allow-download: (Boolean. default: false). Enables the download of the record. At this moment only records provided by Learning Machine are downloadable.

    Example:

    <blockcerts-verifier allow-download></blockcerts-verifier>
  • allow-social-share: (Boolean. default: false). Allows sharing the record on the social networks (LinkedIn, Facebook and Twitter).

    Example:

    <blockcerts-verifier allow-social-share></blockcerts-verifier>
  • disable-auto-verify: (Boolean. default: false). Disables starting automatically the verification sequence as the record is loaded.

    Example:

    <blockcerts-verifier disable-auto-verify></blockcerts-verifier>
  • disable-verify: (Boolean. default: false). Disables verification of the record altogether.

    Example:

    <blockcerts-verifier disable-verify></blockcerts-verifier>
  • display-mode: (String, oneOf('card', 'full'). default: card). Changes the display of a record. card will be a concise summary of the record with a link to the full record, while full will show the actual record as designed by the emitter.

    Example:

    <blockcerts-verifier display-mode="full"></blockcerts-verifier>
  • show-metadata: (Boolean. default: false). Enables showing the metadata of a record.

    Example:

    <blockcerts-verifier show-metadata></blockcerts-verifier>
  • src: (String. default: ''). Allows loading an initial record with no further actions required. src can be either an absolute URL, or a relative path.

    Example:

    <blockcerts-verifier src='../fixtures/valid-certificate-example.json'></blockcerts-verifier>
  • theme: (String. default: 'bright'). Adapts to the background of the page that hosts the component. If the component is displayed on a dark background, you should use the dark option. If it's bright, then use the bright option.

    Example:

    <blockcerts-verifier theme='dark'></blockcerts-verifier>

Event Tracking API

The component will emit events on different moment of the certificate life cycle. To subscribe and track these events you should add on your consumer page event listeners on the window object.

See the event demo page for a working example.

The information is communicated via the detail key of the event.

Supported Events:

  • certificate-load

    Triggered when a certificate has been loaded into the component. Returns:

    • the certificateDefinition (object) on which the action was called.
  • certificate-verify

    Triggered when the verification process of a certificate is started. Returns:

    • the certificateDefinition (object) on which the action was called.
  • certificate-share

    Triggered when a social network link is clicked. Returns:

    • the certificateDefinition (object) on which the action was called.
    • the socialNetwork (string) to which the record was shared.

Development

Viewing Your Element

npm run start

Will make the demo page available on http://localhost:8081/demo/.

Modifying the Sanitizer

The sanitizer is used in order to protect against malicious certificates that could hold XSS attacks. It is an overlay of the xss library, since at times, you might want to be able to configure or adapt the whitelist to your own needs.

To modify it, you should modify the index.js file. Then run:

  npm run build:sanitizer

This will generate the sanitizer.js file, which is then used by the application and the tests.

If you want to work on the sanitizer in watch mode (and auto-generate your changes), use the following command:

  npm run build:sanitizer -- -w

Running Tests

Application Tests

npm run test:application

NOTE: application must be started to run the tests, or at the very least the mock-server via the npm run start:mock-server (automatically included in the npm run start command).

watch mode

npm run test:application:watch

Component Tests

npm run test:components

"watch" mode

npm run test:components:persist

Will allow refreshing the test page: http://localhost:8000/components/blockcerts-verifier/generated-index.html?cli_browser_id=0

Dealing with CSS

The npm run start command will also start a SASS compiler watcher, which means that any stylesheet within the components folder will be transpiled to a polymer component that can be reused within another component. ie:

import CSS from './_components.button-css';
[...]
_render () {
    return html`${CSS}[...]`
}

Using shared styles

To reduce the amount of code duplication, and following the ITCSS philosophy, you may need to import some of the shared-styles in your component. To do so, in your component's SASS file, add the following instruction:

/* in _components.my-component.sass */

@import '../../../shared-styles/objects.text';

[...component styles]

@import '../../../shared-styles/utils.a11y';

Please note that the SASS watcher does not observe changes in the shared styles folder, and will not automatically recompile any consumer stylesheet. You will have to recompile them yourselves (TODO: improve DevX here).

More info

Please have a look through the ADR documentation to get more context around the architecture and the ways of developing a component.