Guides

Embed Portal

Integrate Joyfill within your product using a low-code Portal implementation.

Suggest Edits

Let's integrate Joyfill within your product using a Portal.

📘

You will need a userAccessToken for this which you can get from the users you have within your Joyfill Manager's Organization users. If you haven't already please follow the Getting Started guide.

Embed a Portal

You can embed a Joyfill data exchange experience inside your own product with a Portal.

Think of integrating a Portal in four parts

  1. Include @joyfill/js-sdk
  2. Pass in a userAccessToken, a mountOn HTML element ID (#joyfill-portal), and a modeto tell us if a user is filling out, building, or read-only viewing this form
  3. Trigger an import with Joyfill.Portal.load that injects a Portal
  4. Hook up listeners to react or trigger events throughout your app based on the user's interactions with the embedded form

Specific implementation syntax will vary depending on your programming language.

Implementation

For more information please refer to the JS/React guides.

Install the dependency

npm install @joyfill/sdk-js

Implement your code

// 1. Include the @joyfill/js-sdk and is installed with npm install @joyfill-sdk
import { Portal } from "@joyfill/js-sdk/dist/joyfill.esm.full.js";

// 2. Retrieve and pass in your userAccessToken
const USER_ACCESS_TOKEN = "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.1234567890"

// 3. A function to inject your portal as a child of the provided mountOn ID
Portal.load({
  userAccessToken: USER_ACCESS_TOKEN,
  mode: 'edit', // fill | edit | readonly
  mountOn: '#joyfill-portal',
  submitText: 'Save Changes',
  onUploaded: ({ type, document, fileUpload }) => {
    console.log('on file upload: ', type)
  },
  onChange: ({ type, params, changes, doc }) => {
    console.log('on document changes: ', params, changes, doc)
  }
});

  <body>
    <div class="card">
      <h2>Joyfill Portal Example</h2>
      <p>
        Shows off how the Joyfill Javascript SDK embeddable portal would work.
        <a href="https://joyfill.readme.io/docs/js" target="_blank"> Read Docs.</a>
      </p>
    </div>

    <div id="joyfill-portal"><!-- injected here --></div>
    <script type="module" src="src/index.esm.js"></script>
  </body>

Responding to a form

This is part of the Client SDK that injects a Joyfill Portal.

Portal.load({
	// See options list
});

The following section explains the options available to the Portal.load and when to use them.

Options

PropertyTypeDescription
userAccessTokenStringPass a valid user access token that is retrieved via our API using your organization ID
modeStringCan be of fill, edit, or readonly this respectively sets the mode of the form and can be set dynamically or pre-set if loaded on a page where you know you will always want users to interact with it in a single mode
mountOnStringThe HTML element ID is where the form will be injected as a child element.
submitTextOptional, StringProvide the verbiage of the Save Changes button. The buttons text will reflect whatever value is provided here.
onUploadedOptional, CallbackReturns the base64 data of the uploaded PDF or image. This value always returns an array.
onChangeOptional, CallbackTriggered as a user actively edits/fills a form.

onUploaded

type: String - doc: Object - fileUpload: Array<String>

When a user uploads either an image or a PDF. This always returns an array with the base64 per uploaded item. In the case of an image the array will contain 1 base64 string. In the case of a PDF it will return in order an array of each PDF page as base64.

{
	onUploaded: ({ type, document, fileUpload }) => {
    console.log('on file upload: ', type)
  }
}

onChange

type: String - params: Object - changes: Object - doc: Object

Triggered as a user edits/fills a form. This will return the changes represented as an object of only the things that directly changes but also returns the whole JoyDoc doc in it's changed form. This allows you to respond to any action the user is taking in a form based on its mode.

{
	onChange: ({ type, params, document, fileUpload }) => {
    console.log('on file changed: ', type)
  }
}

Updated over 1 year ago

What’s Next