Simple List

Header and Separators

A list can contain a header to display a title at the top of the list. The header is created by adding the component ion-list-header as the child of the ion-list. Items in the list can be separated using the component ion-item-divider.

Grouping of Items

If a list contains a lot of items, it’s better to group those items for users to view and find them easily. A typical example is the contact list, which is usually grouped by the first character of each contact’s first name. Grouping of items can be done using the component ion-item-group.

Icons

Ionic provides over 700 ready-to-use icons ( http://ionicons.com/ ). These icons can be displayed using the component ion-icon with the name of the icon. For each icon, there may be three variations for different platforms, that is, iOS, iOS-Outline, and Material Design. For example, the icon book has three variations with names ios-book, ios-book-outline, and md-book. If the name book is used, the displayed icon is auto-selected based on the current platform. We can also use the property ios and md to explicitly set the icon for different platforms.

Avatars

Avatars create circular images. They are typically used to display users’ profile images. In Ionic Core, avatars are created by using the component ion-avatar to wrap img elements.

Thumbnails

Thumbnails are rectangular images larger than avatars. In Ionic Core, thumbnails are created by using the component ion-thumnail to wrap img elements .

In Listings 5-6, 5-7, and 5-8, the attribute slot="start" or slot="end" is used in the components ion-icon, ion-avatar, or ion-thumbnail to place the icon, avatar, or thumbnail to the left or right side of the item. There is a difference between slot="start" and slot="end" regarding the element’s position. The element with slot="start" is placed outside of the main item wrapper, but the element with slot="end" is placed inside of the main item wrapper. This is made clear by checking the position of the bottom line that separates each item .

Item Component

Items Component

Empty List

Testing Configuration

Testing Items Component

In Listing 5-20, we created two test specs. The first spec is to test that the list component can display a list of items. The array items contains two items, so there should be two rendered h2 elements for items’ titles, and the text should match the corresponding item’s value of the property title. The fixture.debugElement.queryAll() method queries all the elements matching the given predicate. The By.css() method creates a predicate using a CSS selector. We can use the property nativeElement to get the native DOM element from the query result. The second spec is to test that the list component displays correct message when no items are in the list. The property items is set to an empty array, so there should be a p element with text No items.

Run Tests

To run tests using Karma, we can use npm run test to start the testing. Karma launches the Chrome browser and runs the tests inside of the browser. The testing results will also be reported in the console. Figure 5-1 shows the UI of Karma 3.0.0 running on Chrome 68.

Clicking the DEBUG button in Figure 5-2 shows the debug page. In this page, we can see the results of all specs. We can also use Chrome Developer Tools to debug errors in the test scripts.

Test

Now we need to add a test suite for this page.

Database Structure

Each data value in the database has a unique path to identify it. If you think of the whole JSON object as a file directory, then the path describes how to navigate from the root to a data value. For example, the path of the price of the product with id 00001 is /products/00001/price. The path /orders represents all orders. The path is used when reading or writing data, as well as configuring security rules.

Firebase JavaScript SDK

Firebase provides different SDKs for mobile and web apps to interact with its database. Ionic apps should use the web SDK ( https://firebase.google.com/docs/web/setup ).

To demonstrate the usage of Firebase JavaScript SDK, we use the e-commerce database as the example. The Firebase web SDK is a general library for all kinds of web apps. For Angular apps, AngularFire2 is a better choice that offers tight integration with Angular. In this section, we only discuss the usage of the general web SDK, which is very important to understand how Firebase works. AngularFire2 is used in the Ionic app and will be discussed later.

Setup

We use Firebase console to create a new project first. In the Project Overview page of your newly created Firebase project, clicking Add Firebase to your web app shows a dialog with code ready to be copied into the HTML file; see Figure 5-3.

In Listing 5-30, we set different configuration properties for various Firebase features. PROJECT_ID is the id of the Firebase project.

• apiKey - Core Firebase app.

• authDomain - Firebase Authentication.

• databaseURL - Firebase Realtime Database.

• storageBucket - Firebase Storage.

• messagingSenderId - Firebase Cloud Messaging.

<script src="https://www.gstatic.com/firebasejs/5.4.0/firebasejs"></script>

<script>

  // Initialize Firebase

  var config = {

    apiKey: "<API_KEY>",

    authDomain: "<PROJECT_ID>.firebaseapp.com",

    databaseURL: "https://<PROJECT_ID>.firebaseio.com",

    projectId: "<PROJECT_ID>",

    storageBucket: "<PROJECT_ID>.appspot.com",

    messagingSenderId: "<SENDER_ID>",

  };

  firebase.initializeApp(config) ;

</script>

Listing 5-30

Set up Firebase web SDK

Write Data

The reference object ref can also be used to write data. The method set(value, onComplete) replaces the data at the path of the current reference object. The method set() will override all data under that path, so be careful when using it. The method update(values, onComplete) selectively updates children data specified by relative paths in the value. Only children listed in the values will be replaced. The method update() supports updating multiple values. onComplete is the callback function to invoke after data changes are synchronized to the server. If you prefer to use Promise instead of callback functions, the return value of set() or update() is a firebase.Promise object that is similar to the standard Promise object. Corresponding events, for example, value and child_added, will be triggered after calling methods set() and update().

The Reference object also has the method remove() to remove whole data at the given path, which is the same as using set(null).

Query Data

The major disadvantage of reading data using event listeners on the Reference object is that the whole data at the given path will be read. This could affect performance for large objects or arrays. Sorting also cannot be done either. To filter and sort data under a given path, we can use other methods in the Reference object that return firebase.database.Query objects.

Navigation

AngularFire2

AngularFireObject has methods set(), update(), and remove() to update the data, which have the same meaning as in the Reference object. The method valueChanges() of AngularFireList returns an Observable<any[]>. We can use the directive *ngFor with the pipe async to display the results in the template. AngularFireList has the method push() to add new values to the list. AngularFireList also has the methods set(), update(), and remove() to update the list.

Hacker News API

Implement ItemService

Alternative Model and Service Implementation

The current implementation of ItemService uses Observable operators to watch for changes in the Firebase database and emit values. However, some of those updates may not be necessary. When a story is updated, for example; when the score is updated; or new comments are added, a new Items object that contains all items is emitted from the Observable<Items> object and triggers an update of the whole UI. This is because the operator combineLatest emits a new combined value when any source Observable emits a value. This frequent UI update is not a good user experience. We can improve the performance by changing the data model.

After updating the model, the implementation of ItemService can be simplified. However, it makes the implementation of ItemComponent complicated. As the type of the property item is changed from Item to Observable<Item>, ItemComponent needs to subscribe to the Observable and re-render itself when a new value is emitted. This can be done using the pipe async.

The changes to model and ItemComponent are an alternative way to implement the user story. However, this implementation violates one fundamental principle of designing components like ItemComponent. These components should only have pure rendering logic. The logic of handling Observables in ItemComponent makes it hard to test. This section only provides information about potential alternative implementations. The actual implementation of the example still uses the old model. The aforementioned performance issue will be solved by using state management frameworks in Chapter 6.

Further Improvements

When running this app, you may see the list of stories keeps updating itself. This causes some user experience issues. If the user is currently scrolling down the list of top stories and remote data is updated, then the list may be reordered to reflect the changes. This is annoying as the user’s focus is lost. The list should only be refreshed explicitly by the user, for example, clicking a refresh button or pulling down the list to trigger the refresh. We also need to allow users to see more stories by implementing pagination.

The implementation of the method get() is a bit complicated, but it also shows the beauty of RxJS on how to simplify state management. rawItemIds is an Observable<number[]> object that represents the story ids. The method combineLatest() combines values from rawItemIds and queries to create an Observable of arrays with item ids and Query objects. The operator filter chained after combineLatest() is to make sure that values are only emitted when the property refresh is set to true in the Query object. This is to make sure the story ids are only updated when explicitly requested. Then we use the operator map to extract the ids from the array. Now the itemIds is an Observable of ids that emits the latest ids only when the property refresh is set to true .

The function selector is to combine a Query object and item ids to create Observable<Items> objects. This is done by using the similar approach as in the original implementation of ItemService in Listing 5-25. By using the operator merge, we can get an Observable<Observable<Items>> object. The merge is required to handle the case that Observable itemIds may start emitting values after the Observable queries has emitted the initial Query object. In this case, a single withLatestFrom() doesn’t work because the emitted value in Observable itemIds can only be picked up when the Observable queries emits another value. The operator combineLatest waits until both queries and itemsId to emit at least one value, then combines the values using the function selector. The operator take(1) means only the first value is used. This handles the case when the initial query happens earlier than the first emitted value of item ids. All the rest values come from the second Observable. this.queries.pipe(skip(1), withLatestFrom(itemIds, selector)) uses skip(1) to bypass the first value in queries, because the first value is already captured in the first Observable object. For all of the following values in queries, withLatestFrom() is used to combine Query object and item ids using the function selector. The difference between withLatestFrom and combineLatest is that withLatestFrom only emits a new value when the source Observable emits a value. This can make sure the result Observable only emits Items when a new query is received.

Figure 5-4 shows the top stories page with a button to load more stories.

Pagination and Refresh

Now we can add the UI for pagination and refresh. To build the UI, we need to add buttons to the page.

Pagination

Now we can add the pagination and refresh to the top stories page. We add the HTML markup to show the buttons in the top-stories.component.html file; see Listing 5-48.

<ion-app>

  <ion-header>

    <ion-toolbar>

      <ion-title>Top Stories</ion-title>

    </ion-toolbar>

  </ion-header>

  <ion-content padding>

    <div>

      <ion-button color="light" [disabled]="!hasPrevious()" (click)="previous()">

        <ion-icon name="arrow-back" slot="start"></ion-icon>

        Prev

      </ion-button>

      <ion-button [disabled]="!canRefresh()" (click)="refresh()">

        <ion-icon name="refresh" slot="icon-only"></ion-icon>

      </ion-button>

      <ion-button color="light" [disabled]="!hasNext()" (click)="next()">

          <ion-icon name="arrow-forward" slot="end"></ion-icon>

          Next

        </ion-button>

    </div>

    <app-items [items]="items"></app-items>

  </ion-content>

</ion-app>

Listing 5-48

Add pagination buttons

The file top-stories.component.ts is also updated to use the new methods of ItemService and includes action handlers for pagination and refresh buttons; see Listing 5-49. The value of the property offset is the index of the first loaded item in the whole list. We use offset to determine if the previous or next button should be enabled. Pagination is done by updating the value of offset and invoking the method doLoad().

export class TopStoriesComponent implements OnInit, OnDestroy {

  items: Items;

  private subscription: Subscription;

  private offset = 0;

  private limit = 10;

  constructor(private itemService: ItemService) { }

  ngOnInit() {

    this.subscription = this.itemService.get().subscribe(items => this.items = items);

    this.doLoad(true);

  }

  ngOnDestroy() {

    if (this.subscription) {

      this.subscription.unsubscribe();

    }

  }

  hasPrevious(): boolean {

    return this.offset > 0;

  }

  previous(): void {

    if (!this.hasPrevious()) {

      return;

    }

    this.offset -= this.limit;

    this.doLoad(false);

  }

  hasNext(): boolean {

    return this.items != null && (this.offset + this.limit) < this.items.total;

  }

  next() {

    if (!this.hasNext()) {

      return;

    }

    this.offset += this.limit;

    this.doLoad(false);

  }

  canRefresh(): boolean {

    return this.items != null;

  }

  refresh() {

    if (!this.canRefresh()) {

      return;

    }

    this.offset = 0;

    this.doLoad(true);

  }

  private doLoad(refresh: boolean) {

    this.itemService.load({

      offset: this.offset,

      limit: this.limit,

      refresh,

    });

  }

}

Listing 5-49

Updated TopStories

Figure 5-5 shows the top stories page with buttons for pagination and refresh.

Advanced List

So far, we have implemented the top stories list with basic pagination and refresh support. But the current implementation is more like a traditional web app instead of a mobile app. Mobile apps have their own UI patterns. For pagination and refresh, it’s better to use infinite scrolling and pull-to-refresh.

If infinite scrolling is enabled on the list, when the user scrolls down the list and nearly hits the bottom of the page, an action is triggered to load items of the next page. The user can continuously read through the list without clicking any buttons. Ionic provides built-in support for infinite scrolling with components ion-infinite-scroll and ion-infinite-scroll-content.

Pull-to-refresh is a very common feature in mobile apps. When displaying a list of items, a user can pull down the list and release, then the list will refresh to get the latest data. Ionic also provides built-in support for this feature with components ion-refresher and ion-refresher-content.

The component ion-infinite-scroll and ion-refresher follow the similar usage pattern. After adding these two components into the page, they invoke the provided callback functions when certain events happen, then wait for client code to notify them when the processing is finished. The components ion-infinite-scroll-content and ion-refresher-content are used to customize the feedback UI when the processing is still underway, respectively.

Listing 5-51 is the updated code of top-stories.component.ts to support infinite scrolling and pull-to-refresh. In the method ngOnInit(), when the Observable<Items> emits a new value, we need to check if it’s a refresh request or normal loading request. For refresh requests, we simply assign the value Items to this.items. For a normal loading request, we need to merge the items from the value Items with those items already contained in this.items, so new items are displayed below the old items. The property refresh is newly added to model Items with the value coming from the property refresh in the Query object.

Customization

We can also customize the behaviors of the components ion-infinite-scroll and ion-refresher.

Testing

Loading Indicators

When the user triggers the refresh of the top stories page, a loading indicator should be displayed. Ionic provides a built-in loading component that renders spinner and text in a modal dialog.

In the ItemService, when a new Query object is received, we should immediately emit an Items object to represent the loading event and trigger the display of the loading indicator. When the items loading is finished, the subsequent Items object is emitted and triggers the dismissal of the loading indicator. We add a new Boolean property loading to the model Items.

Error Handling