OA documents are both readable by machines as well as by humans. Every OA document file is stored in a
.json format, allowing any application to process the content within. To present the data file in a human-readable format, a renderer needs to be written.
In this guide, we will build and deploy the renderer to display data from a 📜 Certificate of Completion.
This renderer is a static website that will be embedded in compliant OA viewer. It will take in the OA document in the raw form and generates the corresponding HTML code for rendering.
A template for building your own document renderer has been created for you at our GitHub template repository.
In order to fully understand how developing a renderer work, we will start by cleaning it a bit:
- remove the folder
- remove the folder
Once you have finished the tutorial feel free to clone the repository again and have a look into the deleted files.
After running the Storybook, you should be able to see the templates samples provided at
This is a live preview where you can see the changes when you:
- edit the raw document data in the
- edit the template code to render the data
Now that we have set up the development environment, we can start writing our document renderer. We will first define the data structure of our 📜 Certificate of Completion (COC), followed by writing the renderer to render the HTML code corresponding to the data provided.
To update the raw document data and the corresponding data type, you will need to update the data definition file in
In the above OA document, you will see four root objects:
$template key to describe the template name used to render this display. It should have the following keys:
$template.nameis the name of the template used to render a given OA document. This allows a single document renderer to render for multiple types of OA documents; each with a different template name.
$template.typewill always take the value of
EMBEDDED_RENDERERfor documents rendered in this manner.
$template.urlwill be the remote URL where your OA decentralized renderer resides. For now, we set it to
https://localhost:3000but we will change this value later on in the Deploying Document Renderer section.
name key is a compulsory key to describe the type of OA document. In this case, we are creating an
OpenAttestation Tutorial Certificate of Completion.
OA documents do not have a strict data structure and allows issuers of documents to define their own data schema. The
recipient object is a user-defined object that describes who the certificate is conferred to. In this case, you may replace
John Doe with your name.
In the next section, you will learn more about the OA document schema and how you may define your own data structure. For this guide, we will stick to this simple document.
Now that the structure of the data has been defined, we may proceed to style our 📜 Certificate of Completion.
To change how the data is being rendered, we simply create a React component that takes in the raw document in the
document props and render the corresponding HTML code.
For our 📜 Certificate of Completion, we will simply display the following text:
The first step consist of creating a file
src/templates/coc/template.tsx with the following content:
Now that the component has been created, we can add a story to view it. Next to
src/templates/coc/template.tsx create a file called
template.stories.mdx with the following content:
We can now start storybook and make sure our component looks like expected.
An OA document may have multiple views, each of them rendered in separate tabs. For example, an OA document that is a degree certificate may have the actual certificate as one view, and the transcript as another view in a single template. A demo of the multiple views feature can be found here.
For our 📜 Certificate of Completion, we will only use a single view. Create a file
src/templates/coc/index.tsx with the following content:
templatesmust be an array where each element correspond to a view (or a tab). Here we need only one view.
- Each view must define the following property:
idwhich must be a uniq identifier for this template configuration.
labelwhich will be displayed by tab in the application loading the renderer.
templatewhich is is the component that will be displayed.
src/templates/index.tsx is a file containing the configuration of all the templates available in this renderer.
To register a new template, simply add it as a key to the
registry constant. Take note that the key is case sensitive and must match the
$template.name value defined in the document data.
src/templates/index.tsx with the following code to add the new
If you open
src/index.tsx you will notice that the
registry defined above is used and provided to a component called
FramedDocumentRenderer. This component will handle automatically the connection to the application and will display the correct component depending on your configuration. You can find more information in this github repository
Now, your document renderer is ready to be built and deployed online.
Create a new repository in GitHub and push the code to the new repository. For a step-by-step guide to import source code to GitHub, you may read this guide.
Once you have your code on GitHub, you may build and deploy the site onto Netlify.
Select "New Site From Git" and then "GitHub".
On the build page, enter
npm run build as the "Build command" and
dist as the "Publish Directory" and click on "Deploy Site".
Once the site has been deployed, you will obtain the URL to the document renderer site. In the above example, the URL is
Note that the website will be an empty page when viewed directly. This is normal because it is not meant to be viewed directly through a web browser.
Save the website url for future reference. You should also update the
$template.urlin your OA document.
It is recommended to use a custom domain you own for the document renderer website in production. This prevents locking in to any specific third party hosting provider.
If you are using Netlify, we recommend you to check out how to enable custom domains.