Getting started with Portal in Ember

We've made it simple to get started with Portal with our Portal Ember Component. Here's what you'll need to know to begin.

info

You'll need a license key to continue. Log in to your account to access the Flatfile dashboard. Head to the Flows section in the left-hand navigation pane and find your license key under the Portal tab.

Install and import

ember install @flatfile/ember

This brings the FlatfileButton component into your project.

Configure your settings and usage

To launch, the FlatfileButton component must have settings , customer and licenseKey as arguments.

Basic Usage

<FlatfileButton
  @licenseKey="License Key Here"
  @customer={{hash userId="12345"}}
  @settings={{hash
    type="Contract"
    fields=(array (hash label="Full Name" key="name") (hash label="Email" key="name"))
  }}
>
  Import Contacts
</FlatfileButton>

Here is a list of all the arguments that are configurable with the <FlatfileButton> component. Visit out settings guide to learn about each in greater depth.

• settings - Required - Pass in an object containing the import type and your fields . For a list of the other optional settings, check out our options documentation here.
• customer - Required - Pass in an object that identifies the customer uploading the file. This refers the the setCustomer() function on our SDK, and the same object should be passed in here.
• licenseKey - Required - In order to access our product, a license key is required. The license key can be found in your dashboard by logging in here.
• onInteractionEvent - An optional way to use registerInteractionEventCallback to receive user interaction events. By default, the onInteractionEvent function will be called every 5 seconds, as long as there is user activity inside of Flatfile Portal.
• onCancel - This allows you to pass in a callback function that will run if the user cancels out of the import.
• onData - This allows you to return a new Promise to handle the Flatfile results when returned.
• onRecordChange - This provides access to Flatfile's record hooks when a record changes.
• onRecordInit - This provides access to Flatfile's record hooks when a record initializes.
• fieldHooks - This allows you to pass in one or more field hooks as separate callback functions.

Full FlatfileButton Usage

import Controller from '@ember/controller';

export default class extends Controller {
  onData(results) {
    // do something with the results
    console.log(results);
  }

  onRecordChange(record) {
    return { name: { value: record.name + " from change" };
  }

  onRecordInit(record) {
    return { name: { value: record.name + " from init" };
  }

  onCancel() {
    console.log("cancel");
  }

  fieldHooks = {
    email: (values) =>
      return values.map(([item, index]) => [
        { value: item + ".au" },
        index
      ]);
    }
  }
}

<FlatfileButton
  @licenseKey="License Key Here"
  @customer={{hash userId="12345"}}
  @settings={{hash
    type="Contract"
    fields=(array (hash label="Full Name" key="name") (hash label="Email" key="name"))
  }}
  @onRecordChange={{this.onRecordChange}}
>
  @onRecordInit={{this.onRecordInit}}
  @onCancel={{this.onCancel}}
  @fieldHooks={{this.fieldHooks}}> Import Contacts
</FlatfileButton>

FlatfileProvider Usage

Alternatively, sometimes you may need to open Flatfile from something other than the default button such as a custom component or an anchor link. This can be done by using the <FlatfileProvider> which takes nearly identical arguments as <FlatfileButton>.

<FlatfileProvider
  @licenseKey="License Key Here"
  @customer={{hash userId="12345"}}
  @settings={{hash
    type="Contract"
    fields=(array (hash label="Full Name" key="name") (hash label="Email" key="name"))
  }}
  as |flatfile|
>
  <a href="#" {{on "click" flatfile.open}}>
    FlatfileProvider with html anchor link
  </a>
</FlatfileProvider>

Here is a list of all of the things FlatfileProvider yields.

• flatfile.open - can be tied to an event to open the flatfile importer, this is the default click event for FlatfileButton - {{on "click" flatfile.open}}
• flatfile.state.isLoading - start true if the preload argument is true, otherwise is false until loading starts - boolean - flatfile.state.isLoading
• flatfile.state.isReady - starts false, becomes true when Flatfile has been initialized and loaded - boolean - flatfile.state.isReady