GraphQL

updated doc to 2.x version

GraphQL Backend Service (for Pagination purposes) to get data from a backend server with the help of GraphQL.

Note

Use it when you need to support Pagination (that is when your dataset is rather large, more than 5k rows) with a GraphQL endpoint. If your dataset is small (less than 5k rows), then go with a regular grid with the "dataset.bind" property. SlickGrid can easily handle million of rows using a DataView object, but personally when the dataset is known to be large, I usually use a backend service (OData or GraphQL) and when it's small I go with a regular grid.

Implementation

To connect a backend service into Aurelia-Slickgrid, you simply need to modify your gridOptions and add a declaration of backendServiceApi. See below for the signature and an example further down below.

Demo

Demo Page / Demo ViewModel

TypeScript Signature

backendServiceApi: {
  // On init (or on page load), what action to perform?
  onInit?: (query: string) => Promise<any>;

  // Before executing the query, what action to perform? For example, start a spinner
  preProcess?: () => void;

  // On Processing, we get the query back from the service, and we need to provide a Promise. For example: this.http.get(myGraphqlUrl)
  process: (query: string) => Promise<any>;

  // After executing the query, what action to perform? For example, stop the spinner
  postProcess: (response: any) => void;

  // Backend Service instance (could be OData or GraphQL Service)
  service: BackendService;

  // Throttle the amount of requests sent to the backend. Default to 500ms
  filterTypingDebounce?: number;
}

As you can see, you mainly need to define which service to use (GridODataService or GraphQLService) and finally add the process and postProcess callback.

Grid Definition & call of backendServiceApi

Notes

• Pagination is optional and if not defined, it will use what is set in the Aurelia-Slickgrid - Global Options
• onInit is optional and is there to initialize the grid with data on first page load (typically the same call as process)
  • you could load the grid yourself outside of the gridOptions which is why it's optional
• filterTypingDebounce is a timer (in milliseconds) that waits for user input pause before querying the backend server
  • this is meant to throttle the amount of requests sent to the backend (we don't really want to query every keystroke)
  • 700ms is the default when not provided

Code

import { autoinject } from 'aurelia-framework';
import { HttpClient } from 'aurelia-http-client';
import { GraphqlService } from 'aurelia-slickgrid';

@autoinject()
export class Example {
  columnDefinitions: Column[];
  gridOptions: GridOption;
  dataset = [];

  constructor(http) {
    this.http = http;

    // define the grid options & columns and then create the grid itself
    this.defineGrid();
  }

  defineGrid() {
    this.columnDefinitions = [
      // your column definitions
    ];

    this.gridOptions = {
      enableFiltering: true,
      enablePagination: true,
      pagination: {
        pageSizes: [10, 15, 20, 25, 30, 40, 50, 75, 100],
        pageSize: defaultPageSize,
        totalItems: 0
      },
      backendServiceApi: {
        service: new GraphqlService(),

        // add some options to the backend service to work
        // shown below is the minimum setup for the service to work correctly
        options: {
          columnDefinitions: this.columnDefinitions,
          datasetName: 'users',
          paginationOptions: {
            first: 25,
            offset: 0
          }
        },

        // define all the on Event callbacks
        preProcess: () => this.displaySpinner(true),
        process: (query) => this.getCustomerApiCall(query),
        postProcess: (response) => {
          this.displaySpinner(false);
          this.getCustomerCallback(response);
        },
        filterTypingDebounce: 700,
        service: this.graphqlService
      }
    };
  }

  // Web API call
  getCustomerApiCall(graphqlQuery) {
    // regular Http Client call
    return this.http.createRequest(`/api/getCustomers?${graphqlQuery}`).asGet().send().then(response => response.content);
  
    // or with Fetch Client
    // return this.http.fetch(`/api/getCustomers?${graphqlQuery}`).then(response => response.json());
  }

Extra Query Arguments

You can pass extra query arguments to the GraphQL query via the extraQueryArguments property defined in the backendServiceApi.options. For example let say you have a list of users and your GraphQL query accepts an optional userId, you can write it in code this way:

this.gridOptions = {
      backendServiceApi: {
        service: new GraphqlService(),

        // add some options to the backend service to work
        options: {
          columnDefinitions: this.columnDefinitions,
          executeProcessCommandOnInit: false, // true by default, which load the data on page load
          datasetName: 'users',
          paginationOptions: {
            first: 25,
            offset: 0
          },
          extraQueryArguments: [{
            field: 'userId',
            value: 567
          }]
        },

        // define all the on Event callbacks
        preProcess: () => this.displaySpinner(true),
        process: (query) => this.getCustomerApiCall(query),
        postProcess: (response) => this.displaySpinner(false)
      }
    };
  }

The GraphQL query built with these options will be

// extraQueryArguments will change the userId with
{
  users(first: 20, offset: 0, userId: 567) {
    totalCount,
    nodes {
      id,
      name,
      company
    }
  }
}

Changing/Updating Options Dynamically

You might want to change certain options dynamically, for example passing new set of values to extraQueryArguments. For that you will have to first keep a reference to your GraphqlService instance and then you can call the updateOptions method.

Code Example

export class Example {
  graphqlService: GraphqlService;
  columnDefinitions: Column[];
  gridOptions: GridOption;

  constructor() {
    this.graphqlService = GraphqlService();
  }

  aureliaGridReady(aureliaGrid: AureliaGridInstance) {
    this.aureliaGrid = aureliaGrid;
  }

  ngOnInit(): void {
    this.columnDefinitions = [
      // ...
    ];

    this.gridOptions = {
      backendServiceApi: {
        service: this.graphqlService,
        // ...
      }
    };
  }
}

changeQueryArguments() {
  // update any Backend Service Options you want
  this.graphqlService.updateOptions({
    extraQueryArguments: [{
      field: 'userId',
      value: 567
    }]
  });

  // then make sure to refresh the dataset
  this.aureliaGrid.pluginService.refreshBackendDataset();
}

GraphQL Server Definition

For the implementation of all 3 actions (filtering, sorting, pagination) with your GraphQL Server, please refer to the sections below to configure your GraphQL Schema accordingly.

• Pagination
• Sorting
• Filtering