@accredify/decentralized-renderer-react-components 中文文档教程
decentralized-renderer-react-components
React 组件抽象了与 Open Attestation
去中心化渲染器的通信。 有关此的更多信息:
Setting up
打开命令行,输入
npm install -g typescript
npm install -g copyfiles
将此添加到系统环境变量(Windows)
%APPDATA%\npm
打开cmd 输入 tsc -version
。 它显示应该有类似的东西
Version 3.8.3
Developing the local renderer.
在平台上更新 env 文件
npm run example:renderer
Features
- React - A JavaScript library for building user interfaces.
- Webpack - Component bundler.
- React testing library - Simple and complete testing utilities that encourage good testing practices.
- Jest - JavaScript testing framework used by Facebook.
- ESLint - Make sure you are writing a quality code.
- Prettier - Enforces a consistent style by parsing your code and re-printing it.
- Typescript - JavaScript superset, providing optional static typing
- Circle CI - Automate tests and linting for every push or pull request.
- Storybook - Tool for developing UI components in isolation with documentation.
- Semantic Release - Fully automated version management and package publishing.
- Debug - JS debugging utility that works both in node.js and browsers.
How it works
首先,请确保您阅读了关于 分散式渲染器的初始介绍和解释
为了呈现文档,主机将加载相应的去中心化呈现器(由文档指定)并使用 iframe 将其嵌入。 主机和 iframe 之间的通信是使用 postMessage API 进行的,并使用操作进行设计.
Actions API
所有动作都遵循相同的结构,由 type
和 payload
组成
type
indicates the kind of action being executed, for instanceRENDER_DOCUMENT
to render a document. The type of an action is mandatorypayload
indicates optional data associated to the type, for instance the content of the document to render.
示例:
const renderDocumentAction = {
type: "RENDER_DOCUMENT",
payload: {
document: documentToRender
}
};
const printAction = {
type: "PRINT"
};
From host to frame actions
以下动作列表是为了主机与 iframe 通信(因此必须由嵌入 iframe 的应用程序):
- render a document:
- type:
RENDER_DOCUMENT
- payload: object with 2 properties
- document: (mandatory) document data as returned by
getData
method from @govtechsg/open-attestation - rawDocument: (optional) Open Attestation document
- document: (mandatory) document data as returned by
const action = {
type: "RENDER_DOCUMENT",
payload: {
document: getData(document),
rawDocument: document
}
};
- select a template amongst the one provided by the decentralized renderer (A renderer may provide 1 to many different template to display a document):
- type: "SELECT_TEMPLATE"
- payload: (mandatory) template id to display
const action = {
type: "SELECT_TEMPLATE",
payload: "CUSTOM_TEMPLATE"
};
- request for printing a document
- type: "PRINT"
const action = {
type: "PRINT"
};
有第四个动作可以在 react-native 应用程序的上下文中使用(它不在引擎盖下使用 iframe)
- request for the list of templates for a document. The action directly return the list of templates
- type:
GET_TEMPLATES
- payload: (mandatory) document data as returned by
getData
method from @govtechsg/open-attestation
const action = {
type: "GET_TEMPLATES",
payload: getData(document)
};
From frame to host actions
以下动作列表用于 iframe 与主机通信(因此必须由嵌入 iframe 的应用程序处理):
- provide the full content height of the iframe so that the host can adapt the automatically the size of the embedded iframe.
- type: "UPDATE_HEIGHT"
- payload: (mandatory) full content height of the iframe
const action = {
type: "UPDATE_HEIGHT",
payload: 150
};
- provide the full content width of the iframe so that the host can adapt the automatically the size of the embedded iframe.
- type: "UPDATE_WIDTH"
- payload: (mandatory) full content width of the iframe
const action = {
type: "UPDATE_WIDTH",
payload: 150
};
- provide the name of a field on the document to obfuscate. The value must follow path property as handled by lodash#get
- type: "OBFUSCATE"
- payload: (mandatory) path to the field
const action = {
type: "OBFUSCATE",
payload: "a[0].b.c"
};
- provide the list of templates that can be used to render a document
- type: "UPDATE_TEMPLATES"
- payload: (mandatory) an array where each element is an object composed of a string and a label
const action = {
type: "UPDATE_TEMPLATES",
payload: [
{
id: "certificate",
label: "Certificate"
},
{
id: "transcript",
label: "Transcript"
}
]
};
How to use
该库提供 2 个主要组件
FrameConnector
该组件将创建一个框架并与提供的分散式渲染器建立连接。 属性是:
source
: url to the decentralized renderer that will handle the document to displaydispatch
: function listening for actions triggered by the decentralized rendereronConnected
: function called when the connection to the decentralized renderer has been established. The function will be provided as first parameter another which can be used to send actions to the iframe
请检查 example/application
中的代码以了解如何使用此组件。 您还可以使用命令启动示例应用程序 npm run example:application
FramedDocumentRenderer
此组件将与将应用程序嵌入到 iframe 中的主机建立连接。 属性是:
templateRegistry
: the configuration of the templates handled by the decentralized renderer.templateRegistry
is an object where each key hold an array ofTemplate Configuration
. OneTemplate Configuration
consist of :- id: a unique (withing the current array) identifier of the template
- label: a string to represent what's the template is,
- template: a
Template
, that is to say a react component that will render a document attachmentToComponent
: a function that map attachments to component depending on the attachment type. Currently the library exposes 2 functions:noAttachmentRenderer
: which usesUnsupportedRenderer
(basically it's doing nothing)fullAttachmentRenderer
: which uses all the supported attachment type by the library (see the function). This property default tonoAttachmentRenderer
, to avoid bundles growing huge unnecessarily.
FramedDocumentRenderer
处理与托管应用程序和渲染器通信的所有逻辑:
- it will automatically call
UPDATE_HEIGHT
action, when the iframe is resized or when there is a change within the iframe (using Mutation Observer) - it will automatically call
UPDATE_WIDTH
action, when the iframe is resized or when there is a change within the iframe (using Mutation Observer) - it will automatically call the
Template
to render depending on information provided by the host - it will automatically provide the available templates when a document has been requested for rendering (i.e. it will call
UPDATE_TEMPLATES
action once the document has been renderer) - it will automatically call
OBFUSCATE
action when requested by aTemplate
请检查 example/decentralized-renderer
中的代码以了解如何使用此组件. 可以使用命令启动示例应用
Template (React component)
程序
document
: (mandatory) document data as returned bygetData
method from @govtechsg/open-attestationrawDocument
: (optional) Open Attestation documenthandleObfuscation
: (mandatory) A function to call to handle obfuscation in the document. The value provided must follow path property as handlded by lodash#get
Development
npm run storybook
: to start storybook, create stories and visualize the different componentnpm run test
: to run testsnpm run lint
: to run lintnpm run example:application
: to run the example build with the library to develop an hosting application. Don't forget to update the example if you update this library.npm run example:renderer
: to run the example build with the library to develop a decentralized renderer. Don't forget to update the example if you update this library.
您还 href="https://github.com/Open-Attestation/decentralized-renderer-react-template">github 模板 基于此库
Deployment Guide
开放命令行构建您自己的去中心化渲染器。 首先更新 package.json 中的版本。 输入以下内容
npm run build
npm login
npm publish
decentralized-renderer-react-components
React components abstracting the communication with Open Attestation
decentralized renderer. More information on this:
Setting up
Open command line, enter
npm install -g typescript
npm install -g copyfiles
Add this to the system environment variable (Windows)
%APPDATA%\npm
Open cmd Enter tsc -version
. It show should something simillar
Version 3.8.3
Developing the local renderer.
Update the env file at the platform
npm run example:renderer
Features
- React - A JavaScript library for building user interfaces.
- Webpack - Component bundler.
- React testing library - Simple and complete testing utilities that encourage good testing practices.
- Jest - JavaScript testing framework used by Facebook.
- ESLint - Make sure you are writing a quality code.
- Prettier - Enforces a consistent style by parsing your code and re-printing it.
- Typescript - JavaScript superset, providing optional static typing
- Circle CI - Automate tests and linting for every push or pull request.
- Storybook - Tool for developing UI components in isolation with documentation.
- Semantic Release - Fully automated version management and package publishing.
- Debug - JS debugging utility that works both in node.js and browsers.
How it works
To begin with, makes sure you read the initial introduction and explanation about decentralized renderer
In order to render a document, hosts will load the corresponding decentralized renderer (as specified by the document) and embed it using an iframe. Communication between host and iframe is made using postMessage API and has been designed using actions.
Actions API
All actions follow the same structure and are composed of type
and payload
type
indicates the kind of action being executed, for instanceRENDER_DOCUMENT
to render a document. The type of an action is mandatorypayload
indicates optional data associated to the type, for instance the content of the document to render.
Example:
const renderDocumentAction = {
type: "RENDER_DOCUMENT",
payload: {
document: documentToRender
}
};
const printAction = {
type: "PRINT"
};
From host to frame actions
The following list of actions are made for host to communicate to the iframe (and thus must be handled by application embed in the iframe):
- render a document:
- type:
RENDER_DOCUMENT
- payload: object with 2 properties
- document: (mandatory) document data as returned by
getData
method from @govtechsg/open-attestation - rawDocument: (optional) Open Attestation document
- document: (mandatory) document data as returned by
const action = {
type: "RENDER_DOCUMENT",
payload: {
document: getData(document),
rawDocument: document
}
};
- select a template amongst the one provided by the decentralized renderer (A renderer may provide 1 to many different template to display a document):
- type: "SELECT_TEMPLATE"
- payload: (mandatory) template id to display
const action = {
type: "SELECT_TEMPLATE",
payload: "CUSTOM_TEMPLATE"
};
- request for printing a document
- type: "PRINT"
const action = {
type: "PRINT"
};
There is a 4th action that can be used in the context of react-native application (which doesn't use iframe under the hood)
- request for the list of templates for a document. The action directly return the list of templates
- type:
GET_TEMPLATES
- payload: (mandatory) document data as returned by
getData
method from @govtechsg/open-attestation
const action = {
type: "GET_TEMPLATES",
payload: getData(document)
};
From frame to host actions
The following list of actions are made for iframe to communicate to the host (and thus must be handled by application embedding the iframe):
- provide the full content height of the iframe so that the host can adapt the automatically the size of the embedded iframe.
- type: "UPDATE_HEIGHT"
- payload: (mandatory) full content height of the iframe
const action = {
type: "UPDATE_HEIGHT",
payload: 150
};
- provide the full content width of the iframe so that the host can adapt the automatically the size of the embedded iframe.
- type: "UPDATE_WIDTH"
- payload: (mandatory) full content width of the iframe
const action = {
type: "UPDATE_WIDTH",
payload: 150
};
- provide the name of a field on the document to obfuscate. The value must follow path property as handled by lodash#get
- type: "OBFUSCATE"
- payload: (mandatory) path to the field
const action = {
type: "OBFUSCATE",
payload: "a[0].b.c"
};
- provide the list of templates that can be used to render a document
- type: "UPDATE_TEMPLATES"
- payload: (mandatory) an array where each element is an object composed of a string and a label
const action = {
type: "UPDATE_TEMPLATES",
payload: [
{
id: "certificate",
label: "Certificate"
},
{
id: "transcript",
label: "Transcript"
}
]
};
How to use
The library provide 2 mains components
FrameConnector
This component will create a frame and establish a connection with the provided decentralized renderer. Properties are:
source
: url to the decentralized renderer that will handle the document to displaydispatch
: function listening for actions triggered by the decentralized rendereronConnected
: function called when the connection to the decentralized renderer has been established. The function will be provided as first parameter another which can be used to send actions to the iframe
Please check the code in example/application
to see how to use this component. You can also start the example application using the command npm run example:application
FramedDocumentRenderer
This component will establish a connection with a host embedding the application within an iframe. Properties are:
templateRegistry
: the configuration of the templates handled by the decentralized renderer.templateRegistry
is an object where each key hold an array ofTemplate Configuration
. OneTemplate Configuration
consist of :- id: a unique (withing the current array) identifier of the template
- label: a string to represent what's the template is,
- template: a
Template
, that is to say a react component that will render a document attachmentToComponent
: a function that map attachments to component depending on the attachment type. Currently the library exposes 2 functions:noAttachmentRenderer
: which usesUnsupportedRenderer
(basically it's doing nothing)fullAttachmentRenderer
: which uses all the supported attachment type by the library (see the function). This property default tonoAttachmentRenderer
, to avoid bundles growing huge unnecessarily.
FramedDocumentRenderer
handle all the logic around the communication with the hosted application and the renderer:
- it will automatically call
UPDATE_HEIGHT
action, when the iframe is resized or when there is a change within the iframe (using Mutation Observer) - it will automatically call
UPDATE_WIDTH
action, when the iframe is resized or when there is a change within the iframe (using Mutation Observer) - it will automatically call the
Template
to render depending on information provided by the host - it will automatically provide the available templates when a document has been requested for rendering (i.e. it will call
UPDATE_TEMPLATES
action once the document has been renderer) - it will automatically call
OBFUSCATE
action when requested by aTemplate
Please check the code in example/decentralized-renderer
to see how to use this component. You can also start the example application using the command npm run example:renderer
Template (React component)
Each configured Template
will be provided the following properties, when rendering a document:
document
: (mandatory) document data as returned bygetData
method from @govtechsg/open-attestationrawDocument
: (optional) Open Attestation documenthandleObfuscation
: (mandatory) A function to call to handle obfuscation in the document. The value provided must follow path property as handlded by lodash#get
Development
npm run storybook
: to start storybook, create stories and visualize the different componentnpm run test
: to run testsnpm run lint
: to run lintnpm run example:application
: to run the example build with the library to develop an hosting application. Don't forget to update the example if you update this library.npm run example:renderer
: to run the example build with the library to develop a decentralized renderer. Don't forget to update the example if you update this library.
We also provided a github template to build your own decentralized-renderer based on this library
Deployment Guide
open command line. Update the version in package.json first. Enter the following
npm run build
npm login
npm publish