Building a Complex Component

As they search for a rental, users might also want to narrow their search to a specific city.
While our initial rental listing component only displayed rental information, this new filter component will also allow the user to provide input in the form of filter criteria.

To begin, let's generate our new component.
We'll call this component list-filter, since all we want our component to do is filter the list of rentals based on input.

Notice that below we "wrap" our rentals markup inside the open and closing mentions of list-filter on lines 12 and 20.
This is an example of the block form of a component,
which allows a Handlebars template to be rendered inside the component's template wherever the {{yield}} expression appears.

In this case we are passing, or "yielding", our filter data to the inner markup as a variable called rentals (line 14).

The template contains an {{input}} helper that renders as a text field, in which the user can type a pattern to filter the list of cities used in a search.
The value property of the input will be kept in sync with the value property in the component.

Another way to say this is that the value property of input is bound to the value property of the component.
If the property changes, either by the user typing in the input field, or by assigning a new value to it in our program,
the new value of the property is present in both the rendered web page and in the code.

We use the init hook to seed our initial listings by calling the filter action with an empty value.
Our handleFilterEntry action calls a function called filter based on the value attribute set by the input helper.

The filter function is passed in by the calling object. This is a pattern known as closure actions.

Notice the then function called on the result of calling the filter function.
The code expects the filter function to return a promise.
A promise is a JavaScript object that represents the result of an asynchronous function.
A promise may or may not be executed at the time you receive it.
To account for this, it provides functions, like then that let you give it code it will run when it eventually does receive a result.

To implement the filter function to do the actual filter of rentals by city, we'll create a rentals controller.
Controllers contain actions and properties available to the template of its corresponding route.
In our case we want to generate a controller called rentals.
Ember will know that a controller with the name of rentals will apply to the route with the same name.

When the user types in the text field in our component, the filterByCity action in the controller is called.
This action takes in the value property, and filters the rental data for records in data store that match what the user has typed thus far.
The result of the query is returned to the caller.

For this action to work, we need to replace our Mirage config.js file with the following, so that it can respond to our queries.
Instead of simply returning the list of rentals, our Mirage HTTP GET handler for rentals will return rentals matching the string provided in the URL query parameter called city.

Lets begin by opening the component integration test created when we generated our list-filter component, tests/integration/components/list-filter-test.js.
Remove the default test, and create a new test that verifies that by default, the component will list all items.

Our list-filter component takes a function as an argument, used to find the list of matching rentals based on the filter string provided by the user.
We provide an action function by setting it to the local scope of our test by calling this.on.

this.on will add the provided function to the test local scope as filterByCity, which we can use to provide to the component.

Our filterByCity function is going to pretend to be the action function for our component, that does the actual filtering of the rental list.

If the search input is empty, the function is going to return three cities.
If the the search input is not empty, its going to return just one.
If our component is coded correctly, it should in turn display the three cities on initial render and just show one once a character is given to the search box.

We are not testing the actual filtering of rentals in this test, since it is focused on only the capability of the component.
We will test the full logic of filtering in acceptance tests, described in the next section.

Since our component is expecting the filter process to be asynchronous, we return promises from our filter, using Ember's RSVP library.

Next, we'll add the call to render the component to show the cities we've provided above.

Finally we add a wait call at the end of our test to assert the results.

Ember's wait helper
waits for all asynchronous tasks to complete before running the given function callback.
It returns a promise that we also return from the test.

If you return a promise from a QUnit test, the test will wait to finish until that promise is resolved.
In this case our test completes when the wait helper decides that processing is finished,
and the function we provide that asserts the resulting state is completed.

Now both integration test scenarios should pass.
You can verify this by starting up our test suite by typing ember t -s at the command line.

Acceptance Tests

Now that we've tested that the list-filter component behaves as expected, let's test that the page itself also behaves properly with an acceptance test.
We'll verify that a user visiting the rentals page can enter text into the search field and narrow the list of rentals by city.

Open our existing acceptance test, tests/acceptance/list-rentals-test.js, and implement the test labeled "should filter the list of rentals by city".

The fillIn helper "fills in" the given text into an input field matching the given selector.

The keyEvent helper sends a key stroke event to the UI, simulating the user typing a key.

In app/components/list-filter.js, we have as the top-level element rendered by the component a class called list-filter.
We locate the search input within the component using the selector .list-filter input,
since we know that there is only one input element located in the list-filter component.

Our test fills out "Seattle" as the search criteria in the search field,
and then sends a keyup event to the same field with a code of 69 (the e key) to simulate a user typing.

The test locates the results of the search by finding elements with a class of listing,
which we gave to our rental-listing component in the "Building a Simple Component" section of the tutorial.

Since our data is hard-coded in Mirage, we know that there is only one rental with a city name of "Seattle",
so we assert that the number of listings is one and that the location it displays is named, "Seattle".

The test verifies that after filling in the search input with "Seattle", the rental list reduces from 3 to 1,
and the item displayed shows "Seattle" as the location.

You should be down to only 2 failing tests: One remaining acceptance test failure; and our ESLint test that fails on an unused assert for our unimplemented test.