Overview

A Joyfill changelog is an event created by a Joyfill SDK. The changelog represents a create, update, or deletion action that has been applied (or should be applied) to a document.
A Joyfill changelog is a self-contained object that has all the information needed to apply a change to a document.
Changelogs enable multi-user collaboration on the same document when in fill mode.
- How does this enable multi-user collaboration?
  - A multi-user supported changelog represents an individual change to a field inside the document. With the ability to apply a change at a very targeted level, instead of a requiring a complete overwrite of the whole document, a user can be modifying one field while another user modifies a different field.
    - What if two users modify the same field on the same document? The change that is sent to the Joyfill API last is the one that will be applied to the document.
  - Syncing of multi-user changes happens at the Joyfill API level. Simply use the document changelogs API to sync the user changes together. See API Reference
  - ❗️Important Note - Not all changelogs generated by Joyfill SDK(s) can be used for multi-user collaboration. Only the changelogs marked with Sync Enabled are supported for multi-user collaboration. All changelogs generated in SDK fill mode are supported.

Requirements

JS SDK: >=3.1.0
React Native SDK: >= 0.3.1

Changelog

Note: Not every property listed below will be present on every changelog. Below is a list of all possible properties that could be listed depending upon the type of changelog.

Name	Type	Description
v	Number	Changelog version number.
sdk	String	Specifies the name of the SDK that generated the changelog object.
target	String	Specifies the target change that was made. See Targets below.
_id	String	Specifies the target document _id for the change.
identifier	String	Specifies the target document identifier for the change.
fileId	String	Specifies the target file _id for the change.
pageId	String	Specifies the target page _id for the change.
fieldId	String	Specifies the target field _id for the change.
fieldIdentifier	String	Specifies the target field identifier for the change.
fieldPositionId	String	Specifies the target field position _id for the change.
change	Object	Object containing the properties and values that should be applied for the change.
createdOn	Number	Millisecond timestamp of the change event.

Targets

file.update
page.create
page.update
page.delete
fieldPosition.create
fieldPosition.update
fieldPosition.delete
field.create
field.delete
field.update - multi-user sync enabled
field.value.rowDelete - multi-user sync enabled
field.value.rowUpdate - multi-user sync enabled
field.value.rowMove - multi-user sync enabled
field.value.rowCreate - multi-user sync enabled

Usage Examples


import React, { useState } from 'react';
import { JoyDoc } from '@joyfill/components';

const Form = ({ doc }) => {
  
  const [changes, setChanges] = useState([])

  const handleSaveChangelogs = async () => {
    const updatedDoc = await saveDocumentChangelogs(doc.identifier, changes)
    console.log(updatedDoc);
  }
  
  return (
    <>
      <button onClick={handleSaveChangelogs}>Save</button>
      <JoyDoc
        mode="fill"
        doc={doc}
        onChange={(changelogs, doc) => {
          //Build a list of all changelogs
          setChanges([...changes].concat(changelogs))
        }}
      />
		</>
  );
  
}

const saveDocumentChangeLogs  = async (identifier, changelogs) => {

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

  const data = await response.json();

  return data;

};