Add embeddable component

Install Fullscript.js

Moving into the frontend work, let’s get Fullscript.js installed. We offer two functionally equivalent solutions, compiled from the same source:

  • a UMD (Universal Module Definition)
  • an NPM package (Node Package Manager)

The UMD version is a single JavaScript file packaged for direct consumption by a web browser. The NPM package can be used by any application with a bundler such as Parcel, Webpack etc.

tip

The NPM package contains TypeScript information that enables autocomplete and suggestions in your IDE. For ease of use, we recommend accessing Fullscript.js through the NPM.

Unless otherwise specified, all instructions work for both the UMD Build and NPM package.

fyi

Our Fullscript.js package is open source. You can view its release history (including change log) and code in the GitHub repo.

UMD Build

To use the UMD build, include it as a script tag in any page of your app where you plan to host a Fullscript.js feature:

<script src="https://public-assets.fullscript.com/fullscript.js/2.0.3/fullscript-js.umd.min.js"></script>

tip

Make sure the version in the string above matches the version of Fullscript.js you want to use (usually the latest version!). You can find the available versions here.

NPM Package

To use the NPM package, install it with:

cd your-application-folder
npm install --save @fullscript/fullscript-js

Or if you are using yarn:

cd your-application-folder
yarn add @fullscript/fullscript-js

Load Fullscript.js

In your app’s frontend code, import or require Fullscript.js wherever you need.

import { Fullscript } from "@fullscript/fullscript-js";

Or if using CommonJS style imports:

var Fullscript = require("@fullscript/fullscript-js").Fullscript;

Get your app’s public key

When working with Fullscript.js, your app needs to identify itself to the Fullscript servers. There are two parts to this identification:

  • User identification: OAuth access tokens + session grants (configured earlier)
  • App identification: Fullscript.js public key

Each app you configure in the Fullscript API Dashboard gets assigned a unique Fullscript.js public key. The key is specific to the app and the target Fullscript environment the app works with. For example, the public key for an app configured to use the US Sandbox won’t work for a copy of your app that targets the US Production environment.

To get your public key, go to your app in the Fullscript API Dashboard and select the Fullscript.js settings tab. There are three things to do on this page.

  1. Verify which Fullscript environment your app is targetting. At the top of the page, look for the flag icon and text next to it to identify one of:

    • US Sandbox
    • CA Sandbox
    • US Production
    • CA Production
  2. Click the pencil icon next to Origin URI and add the URLs that your integration will be loaded from. For development, this might just be http://localhost/*, but you can add a space-separated list of any URLs needed. URLs added can be full endpoints or just domains, but they must include the protocol (http can be used in sandbox, https must be used for production).

    fyi

    Fullscript protects your integration by only allowing Fullscript.js to load on pages that come from specific domains. Origin URI is a whitelist of domains that can use Fullscript.js with your app’s credentials.

  3. Hover your mouse over the Reveal button and copy the Fullscript.js public key for the current target environment.

Initialize Fullscript.js

Return to your app’s code and initialize Fullscript.js with the value you just copied as your public key.

var fullscriptClient = Fullscript({
  publicKey: "xxxxx",
  env: "us|ca|us-snd|ca-snd",
});

Set the env attribute to match the Fullscript environment your app targets. During development, use one of our two sandbox environments.

  • us - targets US Production
  • ca - targets CA Production
  • us-snd - targets US Sandbox
  • ca-snd - targets CA Sandbox
tip

The public key is specific to the configured app and the Fullscript environment it’s targeting. When you go live, you’ll configure a new app in the Fullscript API Dashboard, and you’ll need to update both the env and the publicKey in the initialization code.

Add a feature

Now that you have a client, you can add the Fullscript.js feature to your page.

Syntax:

var treatmentPlanFeature = fullscriptClient.create(<feature name>, <options>);

As you know, features in Fullscript.js require authorization from your users. Your app should initially prompt users for this authorization via OAuth (triggering the backend code you created earlier). On subsequent times, you can directly show them the feature.

fyi

Currently the only supported feature is the Treatment Plan writing tool.

Put it on the page

Tell Fullscript.js where to inject the Fullscript feature on your page by adding a DOM element with the feature’s id. The following features are available:

FeatureElement ID
Treatment Plantreatment-plan-container

For example, add the Treatment Plan feature like so:

<div style="width: 100vw; height: 100vh;" id="treatment-plan-container"></div>

fyi

With the code above, the treatment plan container will fill the browser. Read more about Sizing Features below.

Mount and unmount

Now that everything is set up you can mount the feature with mount(). This must be done only after your mount point (created above) is loaded. So we suggest mounting it when your app receives the DOMContentLoaded event.

document.addEventListener("DOMContentLoaded", function () {
  treatmentPlanFeature.mount("treatment-plan-container");
});

When you’re done with the feature, you can remove it with unmount(), or you can navigate away from the page.

treatmentPlanFeature.unmount();

Sizing features

Fullscript.js features fill the parent container’s available space. This means that if the mount point you create has a width and height of 900px, the embedded feature will have a height and width of 900px.

fyi

Fullscript.js features are fully responsive and will reflow if their size changes. For the best performance, we recommend a minimum viewport size of 768 × 1024.

Here’s a fixed size example:

<div style="width: 900px; height: 900px;" id="treatment-plan-container"></div>

If you want to embed the feature into a modal and your modal has strict sizing, you can set the mount point div to take all available space in the modal with the following:

<div id="my-modal">
  <div style="width: 100%; height: 100%;" id="treatment-plan-iframe"></div>
</div>

If you want Fullscript.js to take the full width and height of your page, you can use the following viewport-based units:

<div style="width: 100vw; height: 100vh;" id="treatment-plan-iframe"></div>