A standalone universal viewer & verifier for blockcerts credentials
The component is developed with Polymer 3. To use the component in your project, install it via:
npm i @blockcerts/blockcerts-verifier
<script type="module" 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>Have a look at the Demo Pages to see examples of the usage
By the default, the component will:
- Display a Blockcerts record in
cardmode (concise information) - Will allow verification of a Blockcerts Record
- Enables auto-verification (verification as the record is loaded)
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-download-pdf: (Boolean. default:false). Disables the Download PDF functionality.Example:
<blockcerts-verifier disable-download-pdf></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', 'fullscreen'). default:card). Changes the display of a record.cardwill be a concise summary of the record with a link to the full record.fullwill show the actual record as designed by the emitter.fullscreenwill display a two-column overlay (in desktop) that takes the window dimensions. The certificate displays similar asfull. NOTA: only works for certificates that have adisplayHTMLproperty.
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.srccan be either an absolute URL, a relative path or a stringified certificate definition.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 thedarkoption. If it's bright, then use thebrightoption.Example:
<blockcerts-verifier theme='dark'></blockcerts-verifier>
-
locale: (String. default:'auto', if language code not recognized will default to English (en)). Viewsrc/i18n/langto see the list of supported languages. Contributions welcome.Example:
<blockcerts-verifier locale='fr'></blockcerts-verifier>
-
clickable-urls: (Boolean, default:false). When set to true, the certificate view will identify and convert to clickable links (<a href=...) any url ([http(s)://(www.)]blockcerts.org/[params]) contained in thedisplayHTML` property of the certificate.
Since v4.1.0 of cert-verifier-js accepts custom blockchain explorers, Blockcerts Verifier facilitates communicating such service for the verification process.
As the object would be quite complicated, the option cannot be passed as attribute, but rather via property, as follows:
const explorer = {
parsingFunction: function (): TransactionData {},
serviceURL: 'your-explorer-service.url',
priority: 0 | 1
}
document.addEventListener('DOMContentLoaded', function () {
const bv = document.querySelector('blockcerts-verifier');
bv.explorerAPIs = [explorer];
});See this section: https://github.com/blockchain-certificates/cert-verifier-js#explorerapis to get more information.
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-loadTriggered when a certificate has been loaded into the component. Returns:
- the
certificateDefinition(object) on which the action was called.
- the
-
certificate-verifyTriggered when the verification process of a certificate is started. Returns:
- the
certificateDefinition(object) on which the action was called.
- the
-
certificate-shareTriggered 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.
- the
npm run start
Will make the demo page available on http://localhost:8081/demo/.
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 edit the sanitizer/index.js file.
More specifically if you wish to whitelist some CSS properties, add them to the object whiteListedCssProperties.
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
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
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
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}[...]`
}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).
Please have a look through the ADR documentation to get more context around the architecture and the ways of developing a component.
![dependabot-preview[bot] avatar](https://avatars.githubusercontent.com/in/2141?v=4 "dependabot-preview[bot]")
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent