diff --git a/apps/embedding/react/new_space_quickstart.mdx b/apps/embedding/react/new_space_quickstart.mdx index 2b149df2c..b1ad56bc9 100644 --- a/apps/embedding/react/new_space_quickstart.mdx +++ b/apps/embedding/react/new_space_quickstart.mdx @@ -16,6 +16,7 @@ For synchronous data import/exchange completed in one session, create a new Spac ### Create your file structure +Set up your app to look something like this: Setup your app to look something like this: ``` @@ -23,7 +24,7 @@ Setup your app to look something like this: └── index.html ├── src/ └── blueprint.js - └── index.js + └── index.jsx ├── package.json ``` @@ -31,57 +32,93 @@ In this file structure, your app should have two main directories, `public` and The `public` directory contains the `index.html` file, which is the entry point of the application's front-end. -The `src` directory contains the main components and logic of the application, including the `blueprint.js` file, which defines your schema, and `index.js` from which your application is run. +The `src` directory contains the main components and logic of the application, including the `blueprint.js` file, which defines the shape of your data, and `index.jsx` from which your application is run. The `package.json` file contains the dependencies and scripts for your application. ## Build your importer -### 1. Initialize Flatfile +### 1. Set up Flatfile -Initialize Flatfile to open in a modal. Pass in your `publishableKey` and a new Space will be created on each page load. +Initialize Flatfile to open in a modal. Pass in your `publishableKey` from the Flatfile dashboard ([here's a link to the exact spot](https://platform.flatfile.com/dashboard/keys-and-secrets)) to the `FlatfileProvider` and a new Space will be created on each page load. +Paste your key (it should look like `pk_123456`) where `undefined` is in the `index.jsx` file for the `const PUBLISHABLE_KEY` and you'll be in good shape. +Here are all the files you need to get started, we'll make edits to these in the next steps. -```javascript src/index.js +```jsx src/index.jsx import ReactDOM from "react-dom/client"; -import { usePortal } from "@flatfile/react"; +import { useFlatfile, FlatfileProvider, Sheet } from "@flatfile/react"; import { blueprint } from "./blueprint"; -function App() { - const FlatfilePortal = () => { - return usePortal({ - publishableKey: "pk_1234", - spaceBody: { - namespace: "portal", - }, - }); - }; +// We need to get this from the Flatfile dashboard https://platform.flatfile.com +const PUBLISHABLE_KEY = undefined; - return ; -} +const FlatfilePortal = () => { + const { openPortal } = useFlatfile(); + + return ( + <> + + + + ); +}; + +const App = () => ( + + + +); const root = ReactDOM.createRoot(document.getElementById("root")); root.render(); ``` +```js src/blueprint.js +export const blueprint = { + name: "Contacts", + slug: "contacts", + fields: [ + { + key: "firstName", + type: "string", + label: "First Name", + }, + { + key: "lastName", + type: "string", + label: "Last Name", + }, + { + key: "email", + type: "string", + label: "Email", + }, + ], +}; +``` + ```html public/index.html -
+ + +
+ ``` ```json package.json { - "name": "flatfile-react-app", - "version": "0.1.0", + "name": "example-flatfile-react-app", + "version": "1.0.0", "private": true, "dependencies": { - "@flatfile/react": "^7.3.1", + "@flatfile/react": "^7.9.2", "react": "^18.2.0", "react-dom": "^18.2.0", "react-scripts": "5.0.1", @@ -117,18 +154,18 @@ Build your React project and start the development server: Your browser should automatically open, displaying the Flatfile importer on page load. -### 3. Build a Workbook +### 3. Build on the Workbook Blueprint Now, let's build a Workbook inside the Space for next time. 1. Update your `blueprint.js` with this simple Blueprint. 2. Update `index.html` to import the Workbook. -Next time you open Flatfile, you'll see a Workbook called "Contacts" that has one Sheet with three fields. Your Workbook will also have a Submit action. We will configure this action in the next step. +When you opened Flatfile, you'll see a Workbook called "Contacts" that has one Sheet with three fields. You can modify that however you like according to our [Blueprint outlined here](/blueprint/overview), but as a simple example, we added one more field here for the Contacts' Favorite Color. ```js src/blueprint.js -const blueprint = { +export const blueprint = { "name": "Contacts", "slug": "contacts", "fields": [ @@ -146,164 +183,161 @@ const blueprint = { "key": "email", "type": "string", "label": "Email" + }, + { + "key": "favorite-color", + "type": "string", + "label": "Favorite Color" } ] } ``` -```javascript src/index.js -import ReactDOM from "react-dom/client"; -import { usePortal } from "@flatfile/react"; -import { blueprint } from "./blueprint"; - -function App() { - const FlatfilePortal = () => { - return usePortal({ - publishableKey: "pk_1234", - spaceBody: { - namespace: "portal", - }, - sheet: blueprint, - }); - }; - - return ; -} - -const root = ReactDOM.createRoot(document.getElementById("root")); -root.render(); -``` - -### 4. Set the destination +### 4. Export your data with an `onSubmit()` action. Finally, let's get the data out of our system and to your destination with `onSubmit`. -Once you add this code, when the submit button is clicked, this will be the place you can egress your data. Learn more about [Egress Out](/guides/egress). +Once you add this code, when the submit button is clicked, this will be the place you can egress your data. Learn more about [Egress Out](/guides/egress). Once you have your data, you can do whatever you want with it - from this step you can make another API call to send it where you want. +Keep in mind, this is just a simple example. You can do much more with your data and Flatfile! +We paginate the data in this call so if you have more than 10,000 records worth of data you'll need to handle that. We have lots of ideas on how to handle that, if you'd like to learn more. - -```js public/index.html -window.onload = function () { - FlatFileJavaScript.startFlatfile({ - publishableKey: "pk_1234", - spaceBody: { - namespace: "portal", - }, - sheet: blueprint, - onSubmit: async ({ sheet }) => { - const data = await sheet.allData(); - console.log("onSubmit", data); - }, - }); -}; -``` - -```javascript src/index.js +```jsx src/index.jsx import ReactDOM from "react-dom/client"; -import { usePortal } from "@flatfile/react"; +import { useFlatfile, FlatfileProvider, Sheet } from "@flatfile/react"; import { blueprint } from "./blueprint"; -function App() { - const FlatfilePortal = () => { - return usePortal({ - publishableKey: "pk_1234", - spaceBody: { - namespace: "portal", - }, - sheet: blueprint, - onSubmit: async ({ sheet }) => { - const data = await sheet.allData(); - console.log("onSubmit", data); - }, - }); - }; - return ; -} +const PUBLISHABLE_KEY = undefined; + +const FlatfilePortal = () => { + const { openPortal } = useFlatfile(); + return ( + <> + + { + const data = await sheet.allData(); + console.log("onSubmit", data); + }} + /> + + ); +}; + +const App = () => ( + + + +); const root = ReactDOM.createRoot(document.getElementById("root")); root.render(); + ``` -### 5. Transform Data +### 5. Transform Data with an `onRecordHook` Next, we'll listen for data changes and respond `onRecordHook`, Once you add this code, when a change occurs, we'll log the entered first name and update the last name to "Rock." You'll immediately see this begin to work when you add or update any records. Learn more about [Handling Data](/guides/handling-data) -```javascript src/index.js +```jsx src/index.jsx import ReactDOM from "react-dom/client"; -import { usePortal } from "@flatfile/react"; +import { useFlatfile, FlatfileProvider, Sheet } from "@flatfile/react"; import { blueprint } from "./blueprint"; +const PUBLISHABLE_KEY = undefined; + +const FlatfilePortal = () => { + const { openPortal } = useFlatfile(); + return ( + <> + + { + const data = await sheet.allData(); + console.log("onSubmit", data); + + }} + onRecordHook={(record) => { + record.set("lastName", "Rock"); + // If you added a favorite-color field, you can use it here. + // record.set("favorite-color", "blue"); + return record; + }} + /> + + ); +}; -function App() { - const FlatfilePortal = () => { - return usePortal({ - publishableKey: "pk_1234", - spaceBody: { - namespace: "portal", - }, - sheet: blueprint, - onSubmit: async ({ sheet }) => { - const data = await sheet.allData(); - console.log("onSubmit", data); - }, - onRecordHook: (record) => { - const firstName = record.get("firstName"); - console.log({ firstName }); - record.set("lastName", "Rock"); - return record; - }, - }); - }; - return ; -} +const App = () => ( + + + +); const root = ReactDOM.createRoot(document.getElementById("root")); root.render(); + + ``` ### 6. Match your brand -By attaching a `themeConfig`, we will now override colors in your Space to match your brand. See all of the options here in the [Theming Reference](/guides/theming). +By attaching a `theme`, we will now override colors in your Space to match your brand. See all of the options here in the [Theming Reference](/guides/theming). +The `Space` component can take a number of options to configure and style the component in the Portal instance. In this case, we're adding `theme` to the `metadata` object and giving the Space a `namespace` of `portal`. -```javascript src/index.js +```jsx src/index.jsx import ReactDOM from "react-dom/client"; -import { usePortal } from "@flatfile/react"; +import { useFlatfile, FlatfileProvider, Sheet, Space } from "@flatfile/react"; import { blueprint } from "./blueprint"; +const PUBLISHABLE_KEY = undefined; -function App() { - const FlatfilePortal = () => { - return usePortal({ - publishableKey: "pk_1234", - spaceBody: { +const FlatfilePortal = () => { + const { openPortal } = useFlatfile(); + return ( + { - const data = await sheet.allData(); - console.log("onSubmit", data); - }, - onRecordHook: (record) => { - const firstName = record.get("firstName"); - console.log({ firstName }); - record.set("lastName", "Rock"); - return record; - }, - themeConfig: { - root: { - primaryColor: "red", - textColor: "white", - logo: "https://images.ctfassets.net/hjneo4qi4goj/gL6Blz3kTPdZXWknuIDVx/7bb7c73d93b111ed542d2ed426b42fd5/flatfile.svg", + metadata: { + theme: { + root: { + primaryColor: "red", + textColor: "white", + }, + sidebar: { + logo: "https://images.ctfassets.net/hjneo4qi4goj/gL6Blz3kTPdZXWknuIDVx/7bb7c73d93b111ed542d2ed426b42fd5/flatfile.svg", + }, + }, }, - }, - }); - }; - return ; -} + }} + > + + { + const data = await sheet.allData(); + console.log("onSubmit", data); + }} + onRecordHook={(record) => { + record.set("lastName", "Rock"); + return record; + }} + /> + + ); +}; + +const App = () => ( + + + +); const root = ReactDOM.createRoot(document.getElementById("root")); root.render(); diff --git a/custom.css b/custom.css index 12924127d..2ca0b5dd7 100644 --- a/custom.css +++ b/custom.css @@ -321,7 +321,8 @@ html:not(.dark) .border-primary-light { html:not(.dark) .language-html, html:not(.dark) .language-css, -html:not(.dark) .token.punctuation { +html:not(.dark) .token.punctuation, +html:not(.dark) .token.plain-text { color: #000; }