Ember Addon for https://filestack.com support
npm install ember-filestack
Provides file picking, storing, and converting funtionality from Filestack using filestack-js.
ember install ember-filestack
- Ember.js v3.24 or above
- Ember CLI v3.24 or above
- Node.js v12 or above
ember-filestack supports all ember LTS versions (that means 3.24+ at the moment). With that being said,
it may support versions even older than that.
Your consuming app must depend on ember-auto-import >= 2 in order to use this addon.
There are important changes since v1.0.0. Most will be supported with deprecation notices until v3.0.0. However, there have also been important changes in the underlyng filestack.js module. Please refer to the Filestack API changelog for changes to available options.
Please read our migration guide for changes to environment.js and the Ember components.
- Create your filestack.com key at https://www.filestack.com/.
- Add your filestack.com key in your config/environment.js file
``js`
// config/environment.js
module.exports = function (environment) {
let ENV = {
//...
'ember-filestack': {
apiKey: 'AOkSBYOLvTqK3GzWzQMOuz',
},
};
//...
};
To minimize your quota usage (both bandwidth and process quotas), you can put filestack behind your own CDNs (e.g. AWS CloudFront).
To do that you will want to proxy all urls with the host https://cdn.filestackcontent.com.
Then you can configure your custom CDN url like:
`js`
// config/environment.js
module.exports = function (environment) {
let ENV = {
//...
'ember-filestack': {
apiKey: '
customCDN: '
},
};
//...
};
When customCDN is defined, ember-filestack will ensure that Filestack’s CDN is never accessed directly.
You can add global options for the picker and preview components (read more about them in the next sections).
For that, you can use the pickerOptions and previewOptions keys in the ember-filestack config.
Additionally, any necessary filestack client options must be defined here.
Example:
`js`
// config/environment.js
module.exports = function(environment) {
let ENV = {
//...
'ember-filestack': {
// ...
clientOptions: {
// add any client options here
},
pickerOptions: {
// add any global picker options here
},
previewOptions: {
// add any global preview options here
}
}
};
//...
The file picker is rendered using the component. This component accepts all the available picker options
that the filestack picker accepts. Complete documentation of all the available options can be found
here.
Example:
`hbs
{{#if this.showFilePicker}}
@onUploadDone={{this.fileSelected}}
@onClose={{fn (mut this.showFilePicker) false}}
/>
{{/if}}
`
`jsresult
export default class FileUploader extends Component {
fileSelected(result) {
// is an array of files you've just uploaded`
console.log(result.filesUploaded);
}
}
When you need to generate a filestack url, you should use the {{filestack-url}} helper.
This helper accepts a filestack handle or any image url as the first (and only) positional parameter.
Additionally, you can pass in additional multiple named parameters that correspond to transforms.
The helper accepts all the available transforms that filestack provides. You can check the available transform options
here.
Examples:
`hbs
{{filestack-url this.handleOrUrl}}
{{filestack-url this.handleOrUrl resize=(hash width=50 height=50 fit='scale')}}
{{filestack-url this.handleOrUrl output=(hash format='jpg')}}
{{filestack-url
this.handleOrUrl
output=(hash format='png')
resize=(hash width=500 height=500 fit='max')
}}
`
You can also use the included filestack service to generate image urls:
`js
import Component from '@glimmer/component';
import { computed } from '@ember/object';
import { inject as service } from '@ember/service';
export default class MyComponent extends Component {
@service filestack;
get scaledImage() {
let url = this.args.imageUrl;
let transformations = {
output: {
format: 'png',
},
resize: {
width: 500,
height: 500,
fit: 'max',
},
};
return this.filestack.getUrl(url, transformations);
}
}
`
All of these will respect the customCDN configuration, if present.
Notice that _it is_ possible to write invalid transforms. For example, you can't specify a transform of
resize=(hash fit="some-invalid-value"). Under the hook, filestack-js will validate the passed transform options,
so expect errors if you do something wrong.
Filestack has a feature to preview documents in a nice file previewer. This renders
an iframe with filestack's previewer and it supports multiple formats. Read more about
this feature here.
ember-filestack provides a component that you can use to quickly insert this
iframe anywhere in your DOM.
Example:
`hbs`
This component supports all the preview options that filestack supports.
Complete documentation of all the available options can be found
here.
Sometimes you might need to use the filestack client manually.
To do that, you can use the filestack service initClient method as follows:
`js
import Component from '@glimmer/component';
import { inject as service } from '@ember/service';
export default class MyComponent extends Component {
// inject the filestack service
@service filestack;
async someFunction() {
// Use the promise in case you are not sure that your component will be initialized after filestack has been loaded
let filestack = await this.filestack.initClient();
// do something with filestack
}
}
`
Notice that initClient is asynchronous (returns a Promise). This happens because we lazily initialize and import
filestack client. Please read the next section for more information.
All the filestack javascript and the respective filestack initialization is done only when needed.
This means that, if a user never renders a filepicker or generates a filestack url, your app won't spend any
resources or bandwidth with filestack related work.
With that being said, ember-filestack makes sure that it only initializes filestack once. This means that, for example,this.filestack.initClient()
if you call twice, all the heavy work will be done once. In this example the second call
would return the filestack client immediately.
ember-filestack will no-op on fastboot environments since filestack-js requires access to document` (which isn't available on node).