emberx-file-input


I select files well. I select files very, very well.

x-file-input is a tiny re-usable component which does one thing and
only: binds an action to the native html file selection dialog while
allowing you to render arbitrary HTML to act as the trigger for that
file selector.

This allows you to compose it with whatever other components and
application code you need to make that perfect workflow that involves
selecting files: from uploads to imports.

What you do with the files once they are selected? Welp, that's
between you and your app.

Installation

ember install emberx-file-input

Usage

Bind an action to the file input:

``handlebars
{{x-file-input name="files" multiple=true action=(action "didSelectFiles") alt="Choose a File"}}
`

Whenever the user selects a file, the didSelectfiles action will be
invoked with an array of [File][1] objects.

> Note: Whether the file input is for a single file or mulitple files,
> it will always return an array of File objects upon selection.

In its blockless form, you will need to pass an alt attribute for
the text you would like to be displayed inside the inputs label.

` handlebars
{{x-file-input alt="hello world"}}
`

When passing a block, the HTML inside the block will be used as the
trigger of the file input.

`hbs
{{#x-file-input multiple=true action=(action "didSelectFiles")}}

{{/x-file-input}}
`

Instead of that boring old stock file selector, your users will see
this:

And don't worry, that custom trigger is a form label, so the file input remains
100% accessible.

$3


You can use the accept attribute to only allow specifc types of
files. In this example we only allow .png & .jpg file types.

`hbs
{{#x-file-input multiple=true action=(action "didSelectFiles") accept="image/png,image/jpg"}}

{{/x-file-input}}
`




Customizing the CSS

The whole point of this component is for you to customize your inputs with CSS
and make them look much better than the native inputs. Lets look at a simple
example.

Here is our component. You can see we have a custom class applied to the block
called custom-class. We are going to use that class to apply our styles.

`hbs
{{#x-file-input class="custom-class" action="uploadAPhoto"}}


Shall you upload?


{{/x-file-input}}
`

In our CSS we want to target .custom-class label because the label is the
element that we're making look nice.

`css
.custom-class label {
background: #34495e;
padding: 10px;
color: white;
border-radius: 5px;
}
`

This css will make our button look a little something like this:
!Custom file input styling

We are not done yet! Since we're replicating a native input with
HTML and CSS we have to make sure we replicate all of the "default"
features we get when using a native file input. One of those things is a css
:hover and :focus state. These are often overlooked but are critcal to add.
In your CSS you need to add the following:

`css
.x-file--input:focus + label,
.x-file--input + label:hover {
/ Apply your own hover state /
background-color: #2C3E50;
}
`

And that's it! Your file input is now styled and decked to the nines!
If you would like to see a real
life example checkout the demo page

Resetting the input

To select the same file many times you need to call the resetInput
method that's passed as an argument with the action. For example:

` javascript
actions: {
myAction(files, resetInput) {
// Do something with your files.
// Once you're done, call the reset method:
resetInput();
// Now your input is reset!
}
}
`

Acceptance Testing

You can use the selectFile async helper in acceptance tests to simulate file uploads.

First import the helper in your test-helper.js (or respective file that requires test dependencies)

`javascript
import 'emberx-file-input/test-helpers/select-file-async'

...

`

then in your test:

`javascript
visit('/');
selectFile('.x-file-input', {name: 'test.txt', type: 'text/plain'});

andThen(function() {

...
`

or if the code you're testing needs the object to be an actual file

`javascript
visit('/');

const file = new Blob(['test'], {type: 'image/jpeg'});
selectFile('.x-file-input', file);

andThen(function() {

...
`

The first argument is the class of your x-file-input component. The second argument is an object in place of the file normally returned.

Unit Testing

There is a separate selectFile helper that works in unit/component tests.

`javascript
import 'emberx-file-input/test-helpers/select-file-unit'
`

then in your test:

`javascript
selectFile('.x-file-input', {name: 'test.txt', type: 'text/plain'});

assert.equal($('.something').length, 1, 'Element exists!');
`

EmberX

emberx-file-input is part of the "missing components of ember" collectively
known as emberx:

* emberx-select
* emberx-slider
* emberx-file-input


[1]: https://developer.mozilla.org/en-US/docs/Web/API/File




Code of Conduct


Please note that this project is released with a Contributor Code of
Conduct. By participating in this project you agree to abide by its
terms, which can be found in the CODE_OF_CONDUCT.md` file in this
repository.