filestack-angular

Angular component library which allow you to easily integrate powerful filestack-api into your app.

Table of Contents
- Overview
- Usage
- Installation
- CDN
- Available inputs
- Available outputs
- FilestackService
- Examples
- Documentation
- Development
- Contributing

Overview

filestack-angular is a kind of wrapper on filestack-js sdk which allow you to integrate with filestack service in just a few lines of code. Almost all you are able to do with filestack-js you can also do using this component.

This repository a contains angular workspace with two projects:
- filestack-angular library which contains FilestackAngularModule published via npm
- example angular app to show examples of using FilestackModule features

FilestackAngularModule consists of
- FilestackService - wrapper for a filestack-js client class with added support for an observables
- FilestackTransformPipe - Pipe for easily creating url with transformations in your template
- PickerOverlayComponent - Filestack picker component that will open in overlay mode
- PickerInlineComponent - Filestack picker component that will open in a provided html container
- PickerDropPaneComponent - Filestack drop pane component that will open in a provided html container
which can be also used independently if needed

Usage

$3

Install it through NPM
``bash
npm install filestack-js
npm install @filestack/angular
`
Include `FilestackModule` in `app.module.ts`
`javascript
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';
import { FilestackModule } from '@filestack/angular';
@NgModule({
declarations: [
AppComponent
],
imports: [
BrowserModule,
FilestackModule
],
bootstrap: [AppComponent]
})
export class AppModule {}
`
Use in .html file
`html
apikey="YOUR_API_KEY">

`

$3

In the case you would like to import filestack-module bundle file directly to your app
instead of using npm package you can find it on our cdn:
`
https://static.filestackapi.com/filestack-angular/{MODULE_VERSION}/filestack-angular.umd.min.js
`
`
https://static.filestackapi.com/filestack-angular/{MODULE_VERSION}/filestack-angular.umd.min.js.map
`
where {MODULE_VERSION} is desired version of this package

$3

| Name | Type | Required | Default | Description |
|----------------------------|---------------------------------------------------------------------------------------|-----------------------------------------------------|----------|---------------------------------------------------------------------------------------------------------|
| apikey | String | True | | Filestack api key |
| options | Object | | | Check pickerOptions |
| clientOptions.cname | String | | | Check cname |
| clientOptions.security | Object(Security) | | | Check security |
| clientOptions.sessionCache | Boolean | | | Check sessionCache |
| file | InputFile | | | | Use it to insert a file object for 'upload' action |
| source | String | | | Filestack handle or external url. Use it for 'transform', 'remove', 'metadata' or 'preview' action |

$3

| Name | Type | Required | Default | Description |
|----------------------------|---------------------------------------------------------------------------------------|----------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------|
| uploadSuccess | Subject | | | A subject that emits on uploadSuccess event |
| uploadError | Subject | | | A subject that emits on uploadError event

$3

The FilestackService is an adapter on filestack-js client class
and allows you to work with Observables instead of promises.
Methods get the same input params as client class method.

| method | return | description |
|-------------------|-------------------------------------------------------------------------------------------|------------------------------------------------------------------------------|
| init | void | Init filestack client with your apikey |
| picker | PickerInstance | Open or close picker instance |
| transform | string | Create a transformation url |
| retrieve | Observable | Retrieve an info about a filestack handle |
| metadata | Observable | Access files via their Filestack handles |
| storeURL | Observable | Get info about a filestack handle metadata |
| upload | Observable | Upload a file to the Filestack |
| remove | Observable | Remove a file from the Filestack |
| removeMetadata | Observable | Remove a file only from the Filestack system. The file remains in storage. |
| preview | HTMLIFrameElement | Window | Get preview of uploaded file (need additional addon in your Filestack account)|
| logout | Observable | Clear cloud session from picker procviders |
| setClientInstance | ClientInstance | Put an existing client instance into filestack service |

$3

Below you can find some basic examples.

You can also find and try these examples in angular-filestack-example app

To run it locally type

`
ng serve filestack-angular-example
`
then visit

`
http://localhost:4200/
`

#### Open picker directly after component initialization

component.ts
`typescript
export class AppComponent implements OnInit {
apikey: string;

ngOnInit() {
this.apikey = 'YOUR_API_KEY';
}
}
`

component.html
`html
[apikey]="apikey">

`

#### Open picker by clicking the custom button

component.ts
`typescript
export class AppComponent implements OnInit {
apikey: string;

ngOnInit() {
this.apikey = 'YOUR_API_KEY';
this.onSuccess = (res) => console.log('###onSuccess', res);
this.onError = (err) => console.log('###onErr', err);
}

onUploadSuccess(res: object) {
console.log('###uploadSuccess', res);
}

onUploadError(err: any) {
console.log('###uploadError', err);
}
}
`

component.html
`html
[apikey]="apikey"
(uploadSuccess)="onUploadSuccess($event)"
(uploadError)="onUploadError($event)">
Open picker

`
#### Open picker in inline mode

component.ts
`typescript
export class AppComponent implements OnInit {
apikey: string;

ngOnInit() {
this.apikey = 'YOUR_API_KEY';
}

onUploadSuccess(res: object) {
console.log('###uploadSuccess', res);
}

onUploadError(err: any) {
console.log('###uploadError', err);
}
}
`

component.html
`html
[apikey]="apikey"
(uploadSuccess)="onUploadSuccess($event)"
(uploadError)="onUploadError($event)">
Open picker

`

#### Open picker in drop pane mode

component.ts
`typescript
export class AppComponent implements OnInit {
apikey: string;

ngOnInit() {
this.apikey = 'YOUR_API_KEY';
}

onUploadSuccess(res: object) {
console.log('###uploadSuccess', res);
}

onUploadError(err: any) {
console.log('###uploadError', err);
}
}
`

component.html
`html
[apikey]="apikey"
(uploadSuccess)="onUploadSuccess($event)"
(uploadError)="onUploadError($event)">

`
#### Get transformed url using filestackTransform pipe

component.ts
`typescript
...
import { TransformOptions } from 'filestack-js';

export class AppComponent implements OnInit {
transformOptions: TransformOptions;

constructor(private filestackService: FilestackService) {}

ngOnInit() {
this.transformOptions = {
resize: {
width: 400
},
sepia: {
tone: 80
}
}
}
}
`

component.html
`html

`
#### Select file and upload using sdk client.upload()

component.ts
`typescript
export class AppComponent implements OnInit {
file: any;

constructor(private filestackService: FilestackService) {}

ngOnInit() {
this.filestackService.init('YOUR_API_KEY');
}
fileChanged(e) {
this.file = e.target.files[0];
}
uploadFile() {
this.filestackService.upload(this.file)
.subscribe(res => console.log(res));
}
}
`

component.html
`html

Upload file
`

Documentation

You can find necessary info about avalaible options for actions (Client class methods) at https://filestack.github.io/filestack-js/

Development

After adding changes to FilestackAngularModule in /projects/filestack-angular/src

you need to build this module

`
ng build filestack-angular
`

this command will produce /dist which conatins ready to use filestack module

you can check correctness of it by checking examples from example app:

1. Update api key in /projects/example/src/app/app.component.ts

2. start app locally
`
ng serve example
``
3. visit http://localhost:4200/

Contributing

Any of your contributions or ideas are more than welcome. Please consider that we follow the conventional commits specification to ensure consistent commit messages and changelog formatting.