THE PAGINATOR™

// ______ // <((((((\
// / . }
// ;--..--.|} //(\ '--/--' ) // \ | '-' :'| // \ . -==- .-| // \ .__.' --. // [\ __.--| // /'--. // \ \ .'-. ('-----'/ __/
// \ \ / __>| | '--. | // \ \ | \ | / / / // \ '\ / \ | | _/ / // \ \ \ | | / / // \ \ \ /

this package helps us paginate a web service call, and bind to a UI, so we don't have to re-write the logic.

what kind of pagination does paginator help with?

paginator is designed to work with backend-pagination, where an offset and a limit is provided to limit the results returned from the api.

the caller needs to incremet the offset param as they iterate through pages.

they also may require some logic to bind to a UI, when to refresh results, when to increment, how many pages based on the total number of results and the current limit; etc.

paginator takes care of all of these concerns, so you can just design your endpoint to the pagination spec, wire up paginator, and move on!

backend-pagination endpoint spec - offset & limit

for your endpoint to adhere to the pagination spec, it needs to:

1. require an 'offset' and 'limit' number parameter
2. it must return the results where the result index = offset + 1, up to the limit.
3. it must also return the total number of results from the query. This is important, as it helps the paginator manage state. We will need to pass this value to the paginator everything we refresh.

Here is an example for a c# web api:

    var comicBooks = searchText == null 
        ? _comicBooksRepository.Get() 
        : _comicBooksRepository.Get(x => x.Name == searchText);
    
    // in linq w/ iqueryable, this will execute our query, giving us our total resuls just before we create our response
    var comicBooksList = comicBooks.Skip(offset).Take(limit).ToList();
    return request.CreateResponse(HttpStatusCode.Ok, new { ComicBooks = comicBooksList, TotalResults = comicBooksList.Count });

how to use:

1. grab a paginator, from a provider or new one up.
2. initialize the paginator by passing it a refresh function by using setRefreshFunc(). in your func, you need to set refreshResults() with the total # of results of your query (not the total # returned by api, but the total # your query counted, so we know how many pages we need)

Consider a TypeScript function similar to the one below:

    getComicBookList(searchText: string = null, offset: number, limit: number): Observable<ComicBooksResponse> {
      var hasSearchText = searchText != null && searchText !== "";
      return this.http.get(AppConfig.ApiBase + '/api/comicbooks?offset=' + offset + '&limit=' + limit + (hasSearchText ? '&searchText=' + searchText : ''))
        .map(response => response.json() as [ComicBooksResponse])
        .catch((err) => {
          console.log(err);
          return Observable.of(null);
        });

You would set a refresh func like so:

    this.paginator.setRefreshFunc(
      (offset: number, limit: number): void => {
        this.comicBookService.getComicBookList(this.searchText, offset, limit).subscribe((response: ComicBooksResponse) => {
          this.comicBooks = response.ComicBooks;
          this.paginator.refreshResults(response.TotalResults);
        });
      });

3. then bind your ui to the public properties (page, limit, pagesIndex, nextPage, previousPage, etc)

    <div class="btn-toolbar" role="toolbar" style="margin: 0;" [ngClass]="{'hidden' : (paginator.totalPageCount == 1)}">
      <div class="btn-group">
        <label style="margin-top: 10px;">Page: {{paginator.page}}/{{paginator.totalPageCount}}</label><br />
        <label for="pageSize">Items per page</label>
        <input type="number" name="pageSize" value="{{paginator.limit}}" />
      </div>
      <div class="btn-group pull-right">
        <ul class="pagination">
          <li [ngClass]="{'disabled': (paginator.totalPageCount == 1)}">
            <a (click)="paginator.previousPage()">-</a>
          </li>
          <li *ngFor="let page of paginator.pagesIndex" [ngClass]="{'active': (paginator.page == page)}">
            <a (click)="paginator.page = page">{{page}}</a>
          </li>
          <li [ngClass]="{'disabled': (paginator.page == paginator.totalPageCount)}">
            <a (click)="paginator.nextPage()">+</a>
          </li>
        </ul>
      </div>
    </div>

And that's it! Paginator handles the rest for you, so you don't have to worry about pagination!

refreshing results, e.g. Search Text

You can add additional logic as needed. For instance, our example takes a Search Text parameter. We can automatically implement searching with the paginator. You'll notice we pass our this.searchText field into our service in our refreshFunc. This means anytime refresh is called, it will automatically call the service and pass the search text along, executing an updated query.

  filterByName() {
    this.paginator.refresh();
  }

Note: paginator.refresh(); will automatically set the page to 1 if the totalResults changes.

refreshing results, by changing page

changing the page number will change the page, and automatically call the refresh() func. This is semantically the sae action as the action above.

  filterByName() {
    this.paginator.page = 1;
  }

set default settings in an angular 2 app

NOTE: in Angular 2, you can create a factory provider in your project to configure pagination across your whole app, or per component. This way, you can set the limit for your entire app, or per component.

see: https://angular.io/guide/dependency-injection (search for "factory provider")