README

Flatfile Angular Component - @flatfile/angular

We've made it really simple for you to get started with Flatfile with our new Flatfile Component. Here's what you'll need to know to get started.

Note: This package is ideally suited for Angular version 8+ (or higher)

First, install the dependency via npm:

npm install @flatfile/angular

This will give you access to the <flatfile-button /> component as well as the same basic functionality as our Adapter.

Changelog

NOTE: v3 had some major breaking changes, along with how the tokens/keys are created & passed into the library, read more about these changes here

To view information about the latest releases and any minor/major changes, check out the changelog here.

Getting Started with

import { FlatfileAdapterModule } from '@flatfile/angular';

// Add to your Modules imports: []
imports: [
  FlatfileAdapterModule
]

Within a Components template use the flatfile-button:

The only thing REQUIRED for <flatfile-button> is the Input [token], which you must retrieve from your backend.

More information here

Now let's look at a simple example of getting everything up and running.

import {
  // This interface is optional, but helpful to show you all the available required & optional inputs/outputs available to you
  FlatfileMethods,
  // The "Params" interfaces are useful to strongly type your output methods
  CompleteParams, 
  ErrorParams,
} from "@flatfile/angular";

@Component({
  template: `
    <flatfile-button
      [token]="token"
      (onComplete)="onComplete($event)"
      (onError)="onError($event)"
      class="flatfile-button"
    >
      Text you want to show for the button
    </flatfile-button>
  `,
}) export class MyDemoComponent implements FlatfileMethods {
  /**
   * @NOTE - Call your backend & retrieve your Token, and pass down the license key
   * 👇👇👇
   */
  token = 'YOUR_TOKEN_HERE';
  results;

  onComplete(event: CompleteParams) {
    console.log(`onComplete`);
    console.log(event);

    // Your data!
    this.results = event.data;
  }
  onError(event: ErrorParams) {
    console.log(`onError`);
    console.log(event);
  }
  
}

More advanced use-case example

This is an example showcase all of the other additional (and optional) @Output() methods you could subscribe to.

We're also showcasing how you can style your flatfile-button as well!

Notice we're using all the Params interface (InitParams | LaunchParams etc to strongly type our Output method return values).

Within a Components template use the flatfile-button

import {
  // This interface is optional, but helpful to show you all the available required & optional inputs/outputs available to you
  FlatfileMethods,
  // The "Params" interfaces are useful to strongly type your output methods
  InitParams,
  LaunchParams,
  CompleteParams,
  ErrorParams,
  UploadParams,
} from "@flatfile/angular";

@Component({
  template: `
    <flatfile-button
      [token]="token"
      (onInit)="onInit($event)"
      (onLaunch)="onLaunch($event)"
      (onComplete)="onComplete($event)"
      (onUpload)="onUpload($event)"
      (onError)="onError($event)"
      (onClose)="onClose()"
      class="flatfile-button"
    >
      Text you want to show for the button
    </flatfile-button>
  `,
  /**
   * @note IMPORTANT if you want to style the child component
   * from this "parent" component
   */
  encapsulation: ViewEncapsulation.None,
  /**
   * @note We gave our <flatfile-button class="flatfile-button"> a class,
   * and if we access the "button" inside of that, we can style it however we want!
   */
  styles: [`
    .flatfile-button button {
      border: 0;
      border-radius: 3px;
      padding: 1rem;
      background: #794cff;
      color: #fff;
    }
  `,
}) export class MyDemoComponent implements FlatfileMethods {
  
  /**
   * @NOTE - Call your backend & retrieve your Token, and pass down the license key
   * 👇👇👇
   */
  token = 'YOUR_TOKEN_HERE';

  results;

  /*
   * @Output() methods, make sure they are passed down to <flatfile-button>
   */
  onInit(event: InitParams) {
    console.log(`onInit`);
    console.log(event);
  }
  onUpload(event: UploadParams) {
    console.log(`onUpload`);
    console.log(event);
  }
  onLaunch(event: LaunchParams) {
    console.log(`onLaunch`);
    console.log(event);
  }
  onClose() {
    console.log(`onClose`);
  }
  onComplete(event: CompleteParams) {
    console.log(`onComplete`);
    console.log(event);

    this.results = event.data;
  }
  onError(event: ErrorParams) {
    console.log(`onError`);
    console.log(event);
  }
  
}

Styling the component

As mentioned above, note that in order to style this child-component (from the parent), simply supply a class="" to the <flatfile-button class="some_class_name">, and ensure that your parent component has encapsulation set to ViewEncapsulation.None (showcased above in this advanced demo).

Then you can style it with css via:

.some_class_name button { 
  /* my styles */ 
  background: #000;
  border: 0;
  color: #fff;
}

Running the sample application

npm i && npm start

The same application will be fired up at http://localhost:4200.

Ensure that you've entered in a valid token in the AppComponent file (projects/sample/app.component.ts).

Publishing

Ensure that the correct semantic version has been updated in the projects/angular-adapter/package.json version.

Make sure that if you're updating the (base package) @flatfile/adapter version, to update it within the dependencies array of the package.json within the projects/angular-adapter/ library as well.

Then run:

npm run build:prod
npm run publish:pkg

Usage no npm install needed!