Getting Started

The OneSchema React package contains a React component to help embed OneSchema into your application

Installation

You can install this package with npm:

npm i --save @oneschema/react

Sample usage

import React, { useState } from "react"
import OneSchemaImporter from "@oneschema/react"

function OneSchemaExample() {
  const [isOpen, setIsOpen] = useState(false)

  const handleData = (data) => {
    console.log(data)
  }

  return (
    <div>
      <button onClick={() => setIsOpen(true)}>Import</button>

      <OneSchemaImporter
        /* managing state from your application */
        isOpen={isOpen}
        onRequestClose={() => setIsOpen(false)}
        /* required config values */
        clientId={clientId}
        userJwt={token}
        templateKey={templateKey}
        /* optional config values */
        importConfig={{ type: "local", metadataOnly: false, }}
        devMode={process.env.NODE_ENV !== "production"}
        className="oneschema-importer"
        style={{
          position: "fixed",
          top: 0,
          left: 0,
          width: "100vw",
          height: "100vh",
          zIndex: 1000,
        }}
        /* handling results */
        onSuccess={handleData}
        onCancel={() => console.log("cancelled")}
        onError={(message) => console.log(message)}
      />
    </div>
  )
}

Advanced usage

Changing iframe location

By default, the iframe will append itself to document.body. If you would like the iframe to be included in the component tree, use the inline prop. If you need the iframe to be in a different location, use portals.

Using a session token

You can start an embedding session via API and then use in the session token with the React component

 <OneSchemaImporter
  /* managing state from your application */
  isOpen={isOpen}
  onRequestClose={() => setIsOpen(false)}
  /* required config values */
  clientId={clientId}
  sessionToken={token}
  devMode={process.env.NODE_ENV !== "production"}
  className="oneschema-importer"
  style={{
     position: "fixed",
     top: 0,
     left: 0,
     width: "100vw",
     height: "100vh",
  }}
  /* handling results */
  onSuccess={handleData}
  onCancel={() => console.log("cancelled")}
  onError={(message) => console.log(message)}
/>

API Reference

Table of Contents


OneSchemaImporter React Component

This component is the default export from the @oneschema/react package.

You will need to manage state for whether the embed should be shown through isOpen and onRequestClose

isOpen

Required
Typeboolean
DescriptionWhether the iframe for the embed should be opened

onRequestClose

Optional
TypeFunction (() => void)
DescriptionThis callback is called when the embed import is complete (regardless of success, error, or cancelled). This should set the isOpen prop to false.

clientId

Required
Typestring
DescriptionImporter client Id from the OneSchema dashboard

userJwt

RequiredNote: not required if using session token
Typestring
DescriptionThe JWT to be used for authentication. See generating a secure JSON Web token for a user for more information about setting up a JWT

templateKey

RequiredNote: not required if using session token
Typestring
DescriptionThe key for the template that should be used in the import. See Creating and Editing Templates for more information about template

importConfig

Optional
TypeObject (ImportConfig)
DescriptionConfiguration for how data will be imported out of OneSchema when the import is complete. If not specified, will be a full LocalImportConfig

sessionToken

Optional
Typestring
DescriptionThe session token from creating an embed session via API.

devMode

Optional
Typestring
DescriptionWhether the importer should be in devMode. This will show more helpful information to developers, but should be turned off when you deploy. Defaults to process.env.NODE_ENV !== 'production'

customizationOverrides

Optional
TypeOneSchemaCustomization (See Customizations)
DescriptionValues that will override the saved customization from your dashboard

languageCode

Optional
Typestring
DescriptionOptional language code (like 'en' or 'zh') to force importer language. By default, will use user's set language. Requires enterprise licensing

className

Optional
Typestring
DescriptionThe CSS class of the iframe. Defaults to: oneschema-iframe

style

Optional
TypeReact.CSSProperties
DescriptionCSS styles that should be applied to the iframe

inline

Optional
Typeboolean
DescriptionWhether the iframe should be rendered inside the component tree. By default, false and the iframe will be placed in document.body

baseUrl

Optional
Typestring
DescriptionIf you are a customer with EU Data Residency, set this to <https://embed.eu.oneschema.co>.

onSuccess

Optional
TypeFunction ((data) => void)
DescriptionThis callback is called when the import is completed successfully. It will send data in the format of schema of webhook payload row data as a parameter if webhookKey is not used.

onError

Optional
TypeFunction ((message) => void)
DescriptionThis callback is called when an error occurs during the import. It will send a string message as a parameter

onCancel

Optional
TypeFunction (() => void)
DescriptionThis callback is called when the user cancels the import into OneSchema.

onLaunched

Optional
TypeFunction (() => void)
DescriptionThis callback is called when the modal is displayed.