From 942d5b2444e6b280397bbf79cd89c32be4bd2273 Mon Sep 17 00:00:00 2001 From: Sim Boon Long Date: Fri, 2 Sep 2022 12:08:42 +0800 Subject: [PATCH] chore: add basic demo --- decentralised_rendering.md | 40 +++++++++++++++++++++++--------------- 1 file changed, 24 insertions(+), 16 deletions(-) diff --git a/decentralised_rendering.md b/decentralised_rendering.md index 46fda28..2139e46 100644 --- a/decentralised_rendering.md +++ b/decentralised_rendering.md @@ -15,28 +15,34 @@ It's important to note that a decentralised renderer can be configured to displa The document viewer and the document renderer will rely on [postMessage](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) for the communication, and more specifically OpenAttestation rely on [penpal](https://github.com/Aaronius/penpal), a promise-based library for securely communicating with iframes via postMessage. ## Definitions + The following terms will be used across the document: - `Document Viewer`: Website that loads a `Decentralised Renderer` through an iframe and provide down the certificate for the display. - `Decentralised Renderer` or `Document renderer`: Website responsible of displaying one or more certificates. Usually they are not usable outside a iframe, but keep in mind it's a plain website. -- `Layout`: A template used to display a specific certificate in a document renderer. A document renderer is able to rendere multiple kind of certificates. In other words, a document renderer supports multiple `Layouts` +- `Layout`: A template used to display a specific certificate in a document renderer. A document renderer is able to render multiple kind of certificates. In other words, a document renderer supports multiple `Layouts`. This feature also eases up the supporting of new document schema by simply creating a new `layout`, while maintaining backwards compatibility of rendering previous signed documents. - `View`: A `Layout` may be composed of multiples view. For instance in Opencerts, You may have a view to display the certificate, and a view to display the transcripts. - `Action`: A plain Javascript object used for the communication between the document viewer and the document renderer ## Process overview + The following steps happen to establish the communication. For the moment we will document from a macro perspective only what's going, The information will be more detailed below: + 1. To initiate the connection, the document viewer will load the document renderer into an iframe, using the `$template.url` from the OA certificate. 1. Once established, the document viewer will send the certificate to display to the document renderer, using the `RENDER_DOCUMENT` action 1. The document renderer receive the certificate, and display the correct layout, using the `$template.name` from the OA certificate. These are the minumum steps needed to display a certificate. Additional steps may occur: + - The document send the list of views to the document viewer using the `UPDATE_TEMPLATES` action. Usually this step happens right after the `RENDER_DOCUMENT` action. - The document viewer send the `View` to display using the `SELECT_TEMPLATE` action. Usually, it's an action triggered by a user. You will find below, the list of actions ## Connection + `Penpal` is responsible for establishing the connection between the document viewer and the document renderer. The message sent by penpal to establish the connection is out-of-scope of this document. However to establish the connection correctly, few things must be mentionned: + - The document viewer and the document renderer must both provide one method only, called `dispatch`. This method is the only used for the communication of any `Actions` (see below for a description of the different actions) - The document viewer **may have** to support multiple version of penpal. Indeed, there were a breaking change between penpal v4 and penpal v5, making [the version incompatible](https://github.com/Aaronius/penpal/issues/52). You can also decide to support a specific version of penpal. It's up to the implementer to decide. - The document renderer just need to conform to the version used by the document viewer. We advise to use penpal >= 5. @@ -58,12 +64,12 @@ Examples of actions used: const renderDocumentAction = { type: "RENDER_DOCUMENT", payload: { - document: documentToRender - } + document: documentToRender, + }, }; const printAction = { - type: "PRINT" + type: "PRINT", }; ``` @@ -87,8 +93,8 @@ const action = { type: "RENDER_DOCUMENT", payload: { document: getData(document), - rawDocument: document - } + rawDocument: document, + }, }; ``` @@ -103,7 +109,7 @@ Example: ```js const action = { type: "SELECT_TEMPLATE", - payload: "CUSTOM_TEMPLATE" + payload: "CUSTOM_TEMPLATE", }; ``` @@ -132,7 +138,7 @@ Example: ```js const action = { type: "GET_TEMPLATES", - payload: getData(document) + payload: getData(document), }; ``` @@ -151,7 +157,7 @@ Example: ```js const action = { type: "UPDATE_HEIGHT", - payload: 150 + payload: 150, }; ``` @@ -166,7 +172,7 @@ Example: ```js const action = { type: "OBFUSCATE", - payload: "a[0].b.c" + payload: "a[0].b.c", }; ``` @@ -182,18 +188,20 @@ const action = { payload: [ { id: "certificate", - label: "Certificate" + label: "Certificate", }, { id: "transcript", - label: "Transcript" - } - ] + label: "Transcript", + }, + ], }; ``` ## Implementations -[Decentralised Renderer Template](https://github.com/Open-Attestation/decentralized-renderer-react-template) +Core dependancy for OA decentralised document renderer -> [Decentralised Renderer React Component](https://github.com/Open-Attestation/decentralized-renderer-react-components). + +OA decentralised document renderer, built with React -> [Decentralised Renderer Template](https://github.com/Open-Attestation/decentralized-renderer-react-template). -[Decentralised Renderer React Component](https://github.com/Open-Attestation/decentralized-renderer-react-components) +Basic demostration of OA decentralised document renderer -> [Demo Decentralised Renderer](https://github.com/Open-Attestation/demo-decentralized-renderer).