Skip to content

Latest commit

 

History

History
219 lines (153 loc) · 6.36 KB

README.md

File metadata and controls

219 lines (153 loc) · 6.36 KB
Raw

emberx-file-input

npm version Ember Observer Score Build Status

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:

{{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 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.

{{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.

{{#x-file-input multiple=true action=(action "didSelectFiles")}}
  <img src="http://i-should-buy-a-boat-cat.com" alt="I should buy a boat"/>
{{/x-file-input}}

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

I should buy a boat

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

Configuring file formats with accept

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

{{#x-file-input multiple=true action=(action "didSelectFiles") accept="image/png,image/jpg"}}
  <img src="http://i-should-buy-a-boat-cat.com" alt="I should buy a boat"/>
{{/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.

{{#x-file-input class="custom-class" action="uploadAPhoto"}}
  <h3>Shall you upload?</h3>
{{/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.

.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:

.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:

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)

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

...

then in your test:

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

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.

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

then in your test:

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:

Release Process

Every commit to master is built on CircleCI and the demo url is built using github pages.

Npm releases follow semver, and are ad-hoc and controlled by project owners.

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.