In this guide we are going to explain some of the basic use cases and workflows that can be achieved with Joyfill templates. It will give you practical information on how to work with templates inside your own application.

Setup

Basic understanding of javascript and fetch
Basic understanding of Joyfill API
Completed Setup Guide
Read Key Terminology

SDK Versions

JS SDK >=3.1.0
React Native SDK >=0.3.1

Use Cases

Retrieve a template

Retrieve the Template that you have created in setup guide.


//NOTE: Replace <IDENTIFIER> and <ACCESS_TOKEN> below.
const templateResponse = await fetch("https://api-joy.joyfill.io/v1/templates/<IDENTIFIER>", {
  method: 'GET', 
  mode: 'cors',
  headers: {
    "Authorization": 'Bearer <ACCESS_TOKEN>',
    "Content-Type": 'application/json'
  }
});

//We will use this template in step 2 and 3
const template = templateResponse.data;

Generate a document from a template

A document represents a filled out version of the template. So when you want to fill out a template you simply need to generate a document from the original template.

Joyfill SDK(s) provide a helper method called getDocumentFromTemplate for generating documents from templates. Once you have the new document you can pass it to the SDK to be filled out with data, save it to the API, etc. The generated document is a fully supported and ready to use Joyfill document.

import { getDocumentFromTemplate } from "@joyfill/components';

//Generate a document from a template. .
const newDocPayload = getDocumentFromTemplate(template)

const newDocResponse = await fetch('https://api-joy.joyfill.io/v1/documents', {
  method: 'POST', 
  mode: 'cors',
  headers: {
    "Authorization": `Bearer <ACCESS_TOKEN>`,
    "Content-Type": 'application/json'
  },
  body: JSON.stringify(newDocPayload)
});

const doc = await newDocResponse.json();

console.log('info: ', doc.source); 
//Logs: original template identifier that the document was generated from.

/**
 * Generate a document from a template. Once you have the new document
 * you can pass it to the SDK to be filled out with data, save it to the 
 * API, etc. The document is a fully supported and ready to use Joyfill document.
 * 
 * IMPORTANT NOTE: The `template: originalTemplateIdentifier` on the new document 
 * payload links the new filled out document record to the original template.
 */
const docPayload = {
  name: template.name,
  template: template.identifier,
  files: template.files,
  fields: template.fields
};

const newDocResponse = await fetch('https://api-joy.joyfill.io/v1/documents', {
  method: 'POST', 
  mode: 'cors',
  headers: {
    "Authorization": `Bearer <ACCESS_TOKEN>`,
    "Content-Type": 'application/json'
  },
  body: JSON.stringify(docPayload)
});

const doc = await newDocResponse.json();

console.log('info: ', doc.source); 
//Logs: original template identifier that the document was generated from.

Add a library template to an individual group

To add a library template to an individual group you need to duplicate the original template, assign the group, and then save the new template to the API.

Joyfill SDK(s) provide a helper method called duplicateTemplate to assist in generating new templates from your template library.

import { duplicate } from "@joyfill/components';

//Add template from library to an individual group.
const groupTemplatePayload = duplicate(template, { group: "<GROUP_IDENTIFIER>"})

const groupTemplateResponse = await fetch('https://api-joy.joyfill.io/v1/templates', {
  method: 'POST', 
  mode: 'cors',
  headers: {
    "Authorization": `Bearer <ACCESS_TOKEN>`,
    "Content-Type": 'application/json'
  },
  body: JSON.stringify(groupTemplatePayload)
});

const groupTemplate = await groupTemplateResponse.json();

console.log('info: ', groupTemplate.source); 
//Logs: original template identifier that the group template was generated from.


const groupTemplatePayload = {
  group: "<GROUP_IDENTIFIER>"
  name: template.name,
  source: template.identifier,
  files: template.files,
  fields: template.fields
};

const newDocResponse = await fetch('https://api-joy.joyfill.io/v1/templates', {
  method: 'POST', 
  mode: 'cors',
  headers: {
    "Authorization": `Bearer <ACCESS_TOKEN>`,
    "Content-Type": 'application/json'
  },
  body: JSON.stringify(groupTemplatePayload)
});

const doc = await newDocResponse.json();

console.log('info: ', doc.source); 
//Logs: original template identifier that the document was generated from.

Retrieve filled out template documents

Once you have created multiple documents from a template, those documents can be retrieved by the original template identifier. Simply pass in the template identifier to the api call.

The documents that are retrieved will be returned with a doc.fields property. The doc.fields is where you can easily access the collected field value, identifier, etc.


//Retrieve documents associated with the original template
const docsListResponse = await fetch(`https://api-joy.joyfill.io/v1/documents?template=${template.identifier}&page=1&limit=25`, {
  method: 'GET', 
  mode: 'cors',
  headers: {
    "Authorization": `Bearer <ACCESS_TOKEN>`,
    "Content-Type": 'application/json'
  }
});

const docList = await docListResponse.json();

console.log(docList.data[0].fields);

/* 
Logs an array of objects. You can usethe title and value to display 
the filled out data in a table, list, etc.

[
  {
    _id: String, 
    identifier: String,
    title: String,
    type: String,
    value: Mixed
    ...
  },
  ...
]
*/

Bonus: Relational Database Associations

For anyone coming from a Relational Database world you can think of the returned fields and references used in this guide as follows:

Table - Template
Row - Document
Column - fields[x]._id or fields[x].identifier.
Row Cell - fields[x].value